api-design-principles

SKILL.md

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 resources

PUT: Replace entire resource (idempotent)

PATCH: Partial resource updates

DELETE: Remove resources (idempotent)

2. GraphQL Design Principles

Schema-First Development

Types define your domain model

Queries for reading data

Mutations for modifying data

Subscriptions for real-time updates

Query Structure:

Clients request exactly what they need

Single endpoint, multiple operations

Strongly typed schema

Introspection built-in

3. API Versioning Strategies

URL Versioning:

/api/v1/users
/api/v2/users

Header Versioning:

Accept: application/vnd.api+json; version=1

Query Parameter Versioning:

/api/users?version=1

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 information

Use HTTP Status Codes Correctly: 2xx success, 4xx client errors, 5xx server errors

Version Your API: Plan for breaking changes from day one

Pagination: Always paginate large collections

Rate Limiting: Protect your API with rate limits

Documentation: Use OpenAPI/Swagger for interactive docs

GraphQL APIs

Schema First: Design schema before writing resolvers

Avoid N+1: Use DataLoaders for efficient data fetching

Input Validation: Validate at schema and resolver levels

Error Handling: Return structured errors in mutation payloads

Pagination: Use cursor-based pagination (Relay spec)

Deprecation: Use @deprecated directive for gradual migration

Monitoring: Track query complexity and execution time

Common Pitfalls

Over-fetching/Under-fetching (REST): Fixed in GraphQL but requires DataLoaders

Breaking Changes: Version APIs or use deprecation strategies

Inconsistent Error Formats: Standardize error responses

Missing Rate Limits: APIs without limits are vulnerable to abuse

Poor Documentation: Undocumented APIs frustrate developers

Ignoring HTTP Semantics: POST for idempotent operations breaks expectations

Tight Coupling: API structure shouldn't mirror database schema