skills.rest
gahoccode
gahoccodeCOMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Design REST and GraphQL APIs with resource-oriented patterns and versioning strategies.

Updated Aug 23, 2026
Search Tags:#versioning#documentation#GraphQL#REST#API design
One-click install
npx skills add https://github.com/gahoccode/PRDs --skill api-design-principles-gahoccode
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/gahoccode/PRDs/tree/main/skills/api-design-principles
Command: npx skills add https://github.com/gahoccode/PRDs --skill api-design-principles-gahoccode

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill provides masterful REST and GraphQL API design guidance to create intuitive, scalable, and maintainable interfaces, helping teams standardize API design.

Core Features & Use Cases

  • REST principles (resources, HTTP methods, stable URLs)
  • GraphQL schema-first design, queries, mutations, and subscriptions
  • Versioning strategies (URL, headers, query params)
  • Consistent error handling and documentation patterns
  • Patterns for pagination, filtering, and error payloads

Quick Start

Review your API surface and ensure resources are nouns, endpoints are stable, and versioning strategy is defined.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema
What's the best way to design a REST API that scales?▼

REST API design relies on resource-oriented principles: use nouns for endpoints, apply correct HTTP methods (GET, POST, PUT, DELETE), maintain stable URLs, and implement a versioning strategy (URL, headers, or query parameters). This foundation supports scalability and team standardization.

How do I version an API without breaking existing clients?▼

Versioning strategies include URL paths (/v1/users), custom headers (API-Version), or query parameters (?version=1). Choose one consistently across your API, document the deprecation timeline, and provide migration guides to help clients transition smoothly between versions.

What's the difference between REST and GraphQL API design?▼

REST uses fixed endpoints returning predefined data structures; GraphQL uses a schema-first approach where clients request exactly the fields they need via queries and mutations. REST suits stable, resource-heavy APIs; GraphQL excels when clients need flexible, query-driven data retrieval and reduces over-fetching.

How do I handle pagination and filtering in my API?▼

Implement pagination through limit/offset or cursor-based parameters, and filtering via query parameters matching resource fields. Document these patterns consistently, validate input ranges to prevent abuse, and return metadata (total count, next page token) so clients can navigate results reliably.

Why is consistent error handling important in API design?▼

Consistent error payloads—including status codes, error codes, messages, and details—help clients handle failures predictably. Standardized error responses reduce debugging time, improve developer experience, and make API behavior transparent across all endpoints and versions.

Can I use both REST and GraphQL in the same API?▼

Yes, many teams run parallel REST and GraphQL endpoints serving the same backend logic. GraphQL typically exposes a query layer over existing resources, while REST remains for simpler use cases. Align versioning and error handling strategies across both to maintain consistency.

Related Skills

Explore More Software Engineering Skills→
mahg-esmahg-es
3

api-design

Design REST and GraphQL APIs with OpenAPI 3.1 specifications.

Official
Advanced
jakubciszakjakubciszak
1

api-design

Design REST APIs for Symfony backends with OpenAPI specifications and DTO-based contracts.

Community
Intermediate
cosmixcosmix
53

api-documentation

Generate OpenAPI-based API documentation covering endpoints, schemas, authentication, and errors.

Community
Advanced
erikshafererikshafer

grpc-vs-other-transports

Compare gRPC, Kafka, ASB, and HTTP for CritterCab transport decisions.

Community
Advanced