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

| Method | Idempotent | Safe | Use For | Success Status | |--------|-----------|------|---------|----------------| | GET | Yes | Yes | Read resource | 200 OK | | POST | No | No | Create resource | 201 Created | | PUT | Yes | No | Replace entire resource | 200 OK, 204 No Content | | PATCH | No | No | Update specific fields | 200 OK, 204 No Content | | DELETE | Yes | No | Remove resource | 204 No Content, 200 OK |

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

| Factor | REST | GraphQL | WebSocket | Message Queue | |--------|------|---------|-----------|---------------| | Public API | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐ | | Complex Data | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐ | | Caching | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐ | ⭐ | | Real-time | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | | Simplicity | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |

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:

http
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)

json
{
  "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

| Scenario | Strategy | Why | |----------|----------|-----| | Small datasets (<1000) | Offset-based | Simple, page numbers | | Large datasets (>10K) | Cursor-based | Efficient, handles writes | | Sorted data | Keyset | Consistent results | | Real-time feeds | Cursor-based | Handles new items |

Offset-Based (Simple)

http
GET /users?limit=20&offset=40

Response includes: limit, offset, total, currentPage

Cursor-Based (Scalable)

http
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

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

When exceeded (429):

http
Retry-After: 3600

Strategies

• Per User: 100 requests/hour
• Per API Key: 1000 requests/hour
• Per IP: 50 requests/hour (unauthenticated)
• Tiered: Free (100/hr), Pro (1000/hr), Enterprise (10000/hr)

For implementation patterns, see references/rate-limiting.md

API Security Design

OAuth 2.0 Flows

Authorization Code Flow (Web Apps):

1. Redirect user to authorization server
2. User grants permission
3. Exchange code for access token
4. Use token for API requests

Client Credentials Flow (Service-to-Service):

1. Authenticate with client ID and secret
2. Receive access token
3. Use token for API requests

Scope-Based Authorization

Define granular permissions:

read:users    - Read user data
write:users   - Create/update users
delete:users  - Delete users
admin:*       - Full admin access

API Key Management

Use header-based keys:

http
X-API-Key: sk_live_abc123xyz456

Best practices:

• Prefix with environment: sk_live_*, sk_test_*
• Store hashed keys only
• Support key rotation
• Track last-used timestamp

For complete security patterns, see references/authentication.md

OpenAPI Specification

Basic Structure

yaml
openapi: 3.1.0
info:
  title: User Management API
  version: 2.0.0

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

OpenAPI enables:

• Code generation (server stubs, client SDKs)
• Validation (request/response checking)
• Mock servers (testing against spec)
• Documentation (interactive docs)

For complete OpenAPI examples, see examples/openapi/

AsyncAPI Specification

Event-Driven APIs

AsyncAPI defines message-based APIs (WebSockets, Kafka, MQTT):

yaml
asyncapi: 3.0.0
info:
  title: Order Events API

channels:
  orders/created:
    address: orders.created
    messages:
      orderCreated:
        payload:
          type: object
          properties:
            orderId:
              type: string

For AsyncAPI examples, see examples/asyncapi/

GraphQL Design

Schema Structure

graphql
type User {
  id: ID!
  username: String!
  posts(limit: Int): [Post!]!
}

type Query {
  user(id: ID!): User
  users(limit: Int): [User!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

N+1 Problem Solution

Use DataLoader to batch requests:

javascript
const userLoader = new DataLoader(async (userIds) => {
  // Single query for all users
  const users = await db.users.findByIds(userIds);
  return userIds.map(id => users.find(u => u.id === id));
});

For GraphQL patterns, see references/graphql-design.md

Quick Reference Tables

Pagination Strategy Selection

| Scenario | Strategy | |----------|----------| | Small datasets | Offset-based | | Large datasets | Cursor-based | | Sorted data | Keyset | | Real-time feeds | Cursor-based |

Versioning Strategy Selection

| Factor | URL Path | Header | Media Type | |--------|----------|--------|------------| | Visibility | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐ | | Simplicity | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | | Best For | Most APIs | Internal APIs | Content negotiation |

Integration with Other Skills

• api-patterns: Implement API designs in Express, FastAPI, Go
• auth-security: Implement OAuth2, JWT, session management
• database-design: Design database schemas for API resources
• testing-strategies: API testing (integration, contract, load)
• deploying-applications: Deploy and scale APIs
• observability: Monitor API performance and errors

Additional Resources

Detailed guidance:

• references/rest-design.md - RESTful patterns and best practices
• references/graphql-design.md - GraphQL schema and resolver patterns
• references/versioning-strategies.md - Comprehensive versioning guide
• references/error-handling.md - RFC 7807 implementation details
• references/pagination-patterns.md - Pagination implementation patterns
• references/rate-limiting.md - Rate limiting algorithms and strategies
• references/authentication.md - OAuth2, API keys, scopes
• references/protocol-selection.md - Choosing the right API style

Working examples:

• examples/openapi/ - Complete OpenAPI 3.1 specifications
• examples/asyncapi/ - Event-driven API specifications
• examples/graphql/ - GraphQL schemas and patterns

Validation and tooling:

• scripts/validate-openapi.sh - Validate OpenAPI specifications