api-design-principles

Provide structured guidelines for designing REST and GraphQL APIs.

1|Updated Jan 29, 2026

Search Tags:#design #versioning #documentation #API #GraphQL #REST #best-practices

Ready to run

npx skills add https://github.com/AngelP17/factoryops-console --skill api-design-principles-angelp17

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/AngelP17/factoryops-console/tree/main/factoryops-console/.agent/skills/api-design-principles
Command: npx skills add https://github.com/AngelP17/factoryops-console --skill api-design-principles-angelp17

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

API design often suffers from inconsistent patterns, unclear versioning, and poor developer experience. This skill provides a structured approach to REST and GraphQL API design to help teams produce scalable, maintainable, and developer-friendly interfaces.

Core Features & Use Cases

REST & GraphQL design principles: Guidelines for resource modeling, HTTP semantics, and schema-first GraphQL design.
Versioning and compatibility: Strategies for URL, header, and query-based versioning with deprecation policies.
Practical patterns: Pagination, error handling, HATEOAS, and testing/documentation practices.
Use Case: When starting a new API or auditing an existing one, apply standards to align teams and improve DX.

Quick Start

Use this skill to establish a standardized API design guide for REST or GraphQL projects, covering design decisions, migration paths, and documentation.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema

How do I design a REST API that scales across teams?▼

REST API design requires consistent resource modeling, HTTP semantics, and clear versioning strategies. This skill provides structured guidelines for naming conventions, request/response patterns, and deprecation policies to ensure scalability and maintainability across distributed teams.

What's the best way to version an API without breaking existing clients?▼

API versioning can use URL paths, headers, or query parameters, each with trade-offs. This skill covers versioning strategies, compatibility policies, and migration paths to help you choose the approach that minimizes client disruption while supporting evolution.

How do I structure GraphQL schemas for developer-friendly APIs?▼

GraphQL schema design follows schema-first principles with clear naming, pagination patterns, and error handling conventions. This skill provides design patterns and best practices to build intuitive, self-documenting GraphQL APIs that reduce developer friction.

What should I include in API documentation to improve developer experience?▼

Effective API documentation covers resource definitions, request/response examples, error codes, pagination, and authentication details. This skill includes templates and documentation practices for both REST and GraphQL to ensure clarity and usability.

Can I apply these design principles to an existing API or only new projects?▼

These principles apply to both new APIs and audits of existing ones. The skill provides standardized patterns and migration paths so teams can incrementally align legacy APIs with best practices without full rewrites.

How do I handle errors and pagination consistently across REST and GraphQL?▼

Error handling and pagination differ between REST and GraphQL but both require predictable, documented patterns. This skill covers practical approaches for status codes, error payloads, offset/cursor pagination, and field-level errors to maintain consistency within each paradigm.