designing-apis

name	designing-apis
description	Design APIs that are secure, scalable, and maintainable using RESTful, GraphQL, and event-driven patterns. Use when designing new APIs, evolving existing APIs, or establishing API standards for teams.

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:

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

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)

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

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:

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

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

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

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:

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