Skip to main content Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.
npx skills add wshobson/agents --skill api-design-principles agents claude claude-code subagents anthropic automation
API Design Principles
Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
When to Use This Skill
Designing new REST or GraphQL APIs
Refactoring existing APIs for better usability
Establishing API design standards for your team
Reviewing API specifications before implementation
Migrating between API paradigms (REST to GraphQL, etc.)
Creating developer-friendly API documentation
Optimizing APIs for specific use cases (mobile, third-party integrations)
Core Concepts
1. RESTful Design Principles
Resource-Oriented Architecture
Resources are nouns (users, orders, products), not verbs
Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
URLs represent resource hierarchies
Consistent naming conventions
HTTP Methods Semantics:
GET: Retrieve resources (idempotent, safe)POST: Create new resourcesPUT: Replace entire resource (idempotent)PATCH: Partial resource updates
DELETE: Remove resources (idempotent)
2. GraphQL Design Principles
Types define your domain model
Queries for reading data
Mutations for modifying data
Subscriptions for real-time updates
Clients request exactly what they need
Single endpoint, multiple operations
Strongly typed schema
Introspection built-in
3. API Versioning Strategies /api/v1/users
/api/v2/users
Accept: application/vnd.api+json; version=1
Query Parameter Versioning:
Detailed patterns and worked examples Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.
Best Practices
REST APIs
Consistent Naming : Use plural nouns for collections (/users, not /user)Stateless : Each request contains all necessary informationUse HTTP Status Codes Correctly : 2xx success, 4xx client errors, 5xx server errorsVersion Your API : Plan for breaking changes from day onePagination : Always paginate large collectionsRate Limiting : Protect your API with rate limitsDocumentation : Use OpenAPI/Swagger for interactive docs
GraphQL APIs
Schema First : Design schema before writing resolversAvoid N+1 : Use DataLoaders for efficient data fetchingInput Validation : Validate at schema and resolver levelsError Handling : Return structured errors in mutation payloadsPagination : Use cursor-based pagination (Relay spec)Deprecation : Use @deprecated directive for gradual migrationMonitoring : Track query complexity and execution time
Common Pitfalls
Over-fetching/Under-fetching (REST) : Fixed in GraphQL but requires DataLoadersBreaking Changes : Version APIs or use deprecation strategiesInconsistent Error Formats : Standardize error responsesMissing Rate Limits : APIs without limits are vulnerable to abusePoor Documentation : Undocumented APIs frustrate developersIgnoring HTTP Semantics : POST for idempotent operations breaks expectationsTight Coupling : API structure shouldn't mirror database schema Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
