api-design-principles

Standardize REST and GraphQL API design with review templates and governance checklists.

Updated Feb 3, 2026
One-click install
npx skills add https://github.com/leonardoteodoroo/amino-advanced --skill api-design-principles-leonardoteodoroo
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/leonardoteodoroo/amino-advanced/tree/main/.agent/skills/api-design-principles
Command: npx skills add https://github.com/leonardoteodoroo/amino-advanced --skill api-design-principles-leonardoteodoroo

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

Organizations struggle with inconsistent API designs across REST and GraphQL, leading to fragmented standards, duplicated work, and integration friction.

Core Features & Use Cases

  • Guides resource modeling, endpoint design, versioning, pagination, and error handling to standardize APIs.
  • Supports governance through review checklists, references, and templates, enabling consistent API quality across teams.
  • Provides practical patterns and examples for REST and GraphQL design, documentation templates, and implementation-ready references for faster delivery.

Quick Start

Apply these principles to a new or existing API spec to ensure REST/GraphQL endpoints align with resource orientation, versioning, and error handling.

Frequently Asked Questions about api-design-principles

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I standardize REST and GraphQL API design across multiple teams?

You can standardize REST and GraphQL API design by applying core principles to resource modeling, versioning, error handling, and pagination. This provides ready-to-use templates and review checklists to ensure consistency and reduce integration friction across teams.

What is the best way to handle API versioning and pagination in a new API spec?

The best way to handle API versioning and pagination is to follow standardized design patterns that align endpoints with resource orientation. Applying these principles during planning ensures your API spec maintains consistent quality and governance.

Can I use these API design principles for both planning and reviewing existing endpoints?

Yes, you can apply these API design principles to both planning new endpoints and reviewing existing ones. The principles support governance scenarios by providing review checklists and references to guide resource modeling and error handling.

How do I reduce inconsistencies and confusion in our organization's APIs?

To reduce inconsistencies and confusion in your APIs, apply standardized design patterns for REST and GraphQL during your review process. This enforces consistent API quality through documentation templates and implementation-ready references.

Do I need any specific frameworks to implement proper REST and GraphQL error handling?

You do not need specific frameworks to implement REST and GraphQL error handling. The principles encapsulate core patterns and practical examples that guide error handling and documentation without external dependencies.

REST vs GraphQL: how do I choose the right resource modeling approach for my API?

Choosing between REST and GraphQL resource modeling depends on your specific endpoint needs. This standardization approach provides practical patterns and examples for both paradigms, helping you align your design with resource orientation principles.