Designing APIs

Designing APIs

Design well-structured, scalable APIs using REST, GraphQL, or event-driven patterns. Focus on resource design, versioning, error handling, pagination, rate limiting, and security.

When to Use This Skill

Use when:

• Designing a new REST, GraphQL, or event-driven API
• Establishing API design standards for a team or organization
• Choosing between REST, GraphQL, WebSockets, or message queues
• Planning API versioning and breaking change management
• Defining error response formats and HTTP status code usage
• Implementing pagination, filtering, and rate limiting patterns
• Designing OAuth2 flows or API key authentication
• Creating OpenAPI or AsyncAPI specifications

Do NOT use for:

• Implementation code (use api-patterns skill for Express, FastAPI code)
• Authentication implementation (use auth-security skill for JWT, sessions)
• API testing strategies (use testing-strategies skill)
• API deployment and infrastructure (use deploying-applications skill)

Core Design Principles

Resource-Oriented Design (REST)

Use nouns for resources, not verbs in URLs:

✓ GET    /users              List users
✓ GET    /users/123          Get user 123
✓ POST   /users              Create user
✓ PATCH  /users/123          Update user 123
✓ DELETE /users/123          Delete user 123

✗ GET    /getUsers
✗ POST   /createUser

Nest resources for relationships (limit depth to 2-3 levels):

✓ GET /users/123/posts
✓ GET /users/123/posts/456/comments
✗ GET /users/123/posts/456/comments/789/replies  (too deep)

For complete REST patterns, see references/rest-design.md

HTTP Method Semantics

Idempotent means multiple identical requests have the same effect as one request.

HTTP Status Codes

Success (2xx):

• 200 OK, 201 Created, 204 No Content

Client Errors (4xx):

• 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
• 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests

Server Errors (5xx):

• 500 Internal Server Error, 503 Service Unavailable

For complete status code guide, see references/rest-design.md

API Style Selection

Decision Matrix

Quick Selection

• Public API, CRUD operations → REST
• Complex data, flexible queries → GraphQL
• Real-time, bidirectional → WebSockets
• Event-driven, microservices → Message Queue

For detailed protocol selection, see references/protocol-selection.md

API Versioning

URL Path Versioning (Recommended)

https://api.example.com/v1/users
https://api.example.com/v2/users

Pros: Explicit, easy to implement and test Cons: Maintenance overhead

Alternative Strategies

• Header-Based: Accept-Version: v1
• Media Type: Accept: application/vnd.example.v1+json
• Query Parameter: ?version=1 (not recommended)

Breaking Change Management

Timeline:

1. Month 0: Announce deprecation
2. Months 1-3: Migration period
3. Months 4-6: Deprecation warnings
4. Month 6: Sunset (return 410 Gone)

Include deprecation headers:

Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: </api/v2/users>; rel="successor-version"

For complete versioning guide, see references/versioning-strategies.md

Error Response Standards

RFC 7807 Problem Details (Recommended)

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more fields failed validation",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "code": "INVALID_EMAIL"
    }
  ]
}

Content-Type: application/problem+json

For complete error patterns, see references/error-handling.md

Pagination Patterns

Strategy Selection

Offset-Based (Simple)

GET /users?limit=20&offset=40

Response includes: limit, offset, total, currentPage

Cursor-Based (Scalable)

GET /users?limit=20&cursor=eyJpZCI6MTIzfQ==

Cursor is base64-encoded JSON with position information. Response includes: nextCursor, hasNext

For implementation details, see references/pagination-patterns.md

Rate Limiting

Token Bucket Algorithm

• Each user has bucket with tokens
• Each request consumes 1 token
• Tokens refill at constant rate
• Empty bucket rejects request

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 1672531200

When exceeded (429):

Retry-After: 3600