api-design-patterns

API Design Patterns

Expert guidance for designing scalable, maintainable REST and GraphQL APIs with industry-standard patterns for versioning, pagination, error handling, authentication, and service contracts.

When to Use This Skill

• Designing new REST or GraphQL APIs from scratch
• Refactoring existing APIs for better scalability and consistency
• Defining service contracts for microservices architectures
• Implementing versioning strategies for API evolution
• Standardizing error handling and response formats across services
• Designing pagination for large datasets
• Implementing HATEOAS or hypermedia-driven APIs
• Creating API specifications (OpenAPI, GraphQL Schema)

Quick Reference

Topic	Load reference
Design Process	skills/api-design-patterns/references/design-process.md

Core Principles

1. Resource-Oriented Design (REST)

URLs represent resources, not actions:

✓ GET    /users/123
✓ POST   /users
✓ PUT    /users/123
✓ DELETE /users/123

✗ GET    /getUser?id=123
✗ POST   /createUser
✗ POST   /deleteUser

Use HTTP methods semantically:

• GET: Retrieve resource(s), idempotent, cacheable
• POST: Create resource, non-idempotent
• PUT: Replace entire resource, idempotent
• PATCH: Partial update, idempotent
• DELETE: Remove resource, idempotent

2. Consistent Naming Conventions

Resources:        /users, /orders, /products (plural nouns)
Nested:           /users/123/orders
Collections:      /users?status=active&page=2
Sub-resources:    /users/123/settings
Actions (rare):   /users/123/activate (POST)

3. HTTP Status Codes

Success:

• 200 OK: Standard response for GET, PUT, PATCH
• 201 Created: Resource created (POST), return Location header
• 202 Accepted: Async processing started
• 204 No Content: Success with no response body (DELETE)

Client Errors:

• 400 Bad Request: Invalid syntax or validation failure
• 401 Unauthorized: Authentication required or failed
• 403 Forbidden: Authenticated but insufficient permissions
• 404 Not Found: Resource doesn't exist
• 409 Conflict: State conflict (duplicate, version mismatch)
• 422 Unprocessable Entity: Semantic validation failure
• 429 Too Many Requests: Rate limit exceeded