API Design Patterns

A comprehensive skill for designing, documenting, and implementing APIs that developers love to use. Covers REST, GraphQL, and hybrid approaches with emphasis on consistency, discoverability, and maintainability.

When to Use

Designing new REST or GraphQL APIs from scratch
Reviewing existing API contracts for consistency and best practices
Evaluating API technologies and frameworks
Implementing API versioning strategies
Designing authentication and authorization flows
Creating OpenAPI/Swagger specifications
Building developer-friendly API documentation

Core Principles

1. Contract-First Design

Define the API contract before implementation. This enables parallel development, clearer communication, and better documentation.

DESIGN SEQUENCE:
1. IDENTIFY use cases and consumer needs
2. MODEL resources and their relationships
3. DEFINE operations (CRUD + custom actions)
4. SPECIFY request/response schemas
5. DOCUMENT error scenarios
6. VALIDATE with consumers before implementing

2. Consistency Over Cleverness

APIs should be predictable. Developers should be able to guess how an endpoint works based on patterns established elsewhere in the API.

CONSISTENCY CHECKLIST:
- Naming conventions (plural nouns, kebab-case)
- Response envelope structure
- Error format across all endpoints
- Pagination approach
- Query parameter patterns
- Date/time formatting (ISO 8601)

3. Design for Evolution

APIs must evolve without breaking existing consumers. Plan for change from day one.

EVOLUTION STRATEGIES:
- Additive changes only (new fields, endpoints)
- Deprecation with sunset periods
- Version negotiation (headers, URL paths)
- Backward compatibility testing

REST API Patterns

Resource Modeling

Resources represent business entities. URLs should reflect the resource hierarchy.

GOOD:
GET    /users                    # List users
POST   /users                    # Create user
GET    /users/{id}               # Get user
PATCH  /users/{id}               # Partial update
DELETE /users/{id}               # Delete user
GET    /users/{id}/orders        # User's orders (sub-resource)

AVOID:
GET    /getUsers                 # Verbs in URLs
POST   /createNewUser            # Redundant verbs
GET    /user-list                # Inconsistent naming
POST   /users/{id}/delete        # Wrong HTTP method

HTTP Method Semantics

Method	Usage	Idempotent	Safe
GET	Retrieve resource(s)	Yes	Yes
POST	Create resource, trigger action	No	No
PUT	Replace entire resource	Yes	No
PATCH	Partial update	Yes	No
DELETE	Remove resource	Yes	No
OPTIONS	CORS preflight, capability discovery	Yes	Yes

Status Code Selection

SUCCESS:
200 OK           - Successful GET, PUT, PATCH, DELETE
201 Created      - Successful POST (include Location header)
202 Accepted     - Async operation started
204 No Content   - Success with no response body

CLIENT ERRORS:
400 Bad Request  - Malformed request, validation failure
401 Unauthorized - Missing or invalid authentication
403 Forbidden    - Authenticated but not authorized
404 Not Found    - Resource doesn't exist
409 Conflict     - State conflict (duplicate, version mismatch)
422 Unprocessable- Semantically invalid (business rule violation)
429 Too Many     - Rate limit exceeded

SERVER ERRORS:
500 Internal     - Unexpected server error
502 Bad Gateway  - Upstream service failure
503 Unavailable  - Temporary overload or maintenance
504 Gateway Timeout - Upstream timeout

Error Response Format

Standardize error responses across all endpoints:

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email must be a valid email address"
      }
    ],
    "requestId": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z",
    "documentation": "https://api.example.com/docs/errors#VALIDATION_ERROR"
  }
}

Pagination Patterns

Offset-Based (Simple, not for large datasets)

GET /users?offset=20&limit=10

Response:
{
  "data": [...],
  "pagination": {
    "total": 150,
    "offset": 20,
    "limit": 10,
    "hasMore": true
  }
}

Cursor-Based (Recommended for large datasets)

GET /users?cursor=eyJpZCI6MTAwfQ&limit=10

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTEwfQ",
    "prevCursor": "eyJpZCI6OTB9",
    "hasMore": true
  }
}

Filtering and Sorting

FILTERING:
GET /users?status=active                    # Exact match
GET /users?created_after=2025-01-01         # Date range
GET /users?role=admin,moderator             # Multiple values
GET /users?search=john                      # Full-text search

SORTING:
GET /users?sort=created_at                  # Ascending (default)
GET /users?sort=-created_at                 # Descending (prefix -)
GET /users?sort=status,-created_at          # Multiple fields

FIELD SELECTION:
GET /users?fields=id,name,email             # Sparse fieldsets
GET /users?expand=organization              # Include related

GraphQL Patterns

Schema Design Principles

graphql

# Use clear, descriptive type names
type User {
  id: ID!
  email: String!
  displayName: String!
  createdAt: DateTime!

  # Relationships with clear naming
  organization: Organization
  orders(first: Int, after: String): OrderConnection!
}

# Use connections for paginated lists
type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type OrderEdge {
  node: Order!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

Query Design

graphql

type Query {
  # Single resource by ID
  user(id: ID!): User

  # List with filtering and pagination
  users(
    filter: UserFilter
    first: Int
    after: String
    orderBy: UserOrderBy
  ): UserConnection!

  # Viewer pattern for current user
  viewer: User
}

input UserFilter {
  status: UserStatus
  organizationId: ID
  searchQuery: String
}

enum UserOrderBy {
  CREATED_AT_ASC
  CREATED_AT_DESC
  NAME_ASC
  NAME_DESC
}

Mutation Design

graphql

type Mutation {
  # Use input types for complex mutations
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!
}

input CreateUserInput {
  email: String!
  displayName: String!
  organizationId: ID
}

# Payload types for consistent responses
type CreateUserPayload {
  user: User
  errors: [UserError!]!
}

type UserError {
  field: String
  code: String!
  message: String!
}

N+1 Query Prevention

STRATEGIES:
1. DataLoader pattern for batching
2. Query complexity analysis and limits
3. Depth limiting
4. Field-level cost calculation
5. Persisted queries for production

API Versioning Strategies

URL Path Versioning

GET /v1/users
GET /v2/users

PROS:
- Explicit and visible
- Easy to route in infrastructure
- Clear in logs and monitoring

CONS:
- URL pollution
- Harder to deprecate gracefully

Header Versioning

GET /users
Accept: application/vnd.api+json; version=2

PROS:
- Clean URLs
- Content negotiation friendly
- Easier partial versioning

CONS:
- Less visible
- Harder to test in browser

Query Parameter Versioning

GET /users?api-version=2025-01-15

PROS:
- Easy to test
- Visible in URLs
- Date-based versions are intuitive

CONS:
- Clutters query strings
- Easy to forget

Recommended: Dual Approach

1. Major versions in URL path: /v1/, /v2/
2. Minor versions via header: API-Version: 2025-01-15
3. Default to latest minor within major
4. Sunset headers for deprecation warnings

Authentication Patterns

API Keys

USAGE: Server-to-server, rate limiting, analytics
TRANSPORT: Header (Authorization: ApiKey xxx) or query param

SECURITY:
- Rotate keys regularly
- Different keys for environments
- Scope keys to specific operations
- Never expose in client-side code

OAuth 2.0 / OIDC

FLOWS:
- Authorization Code + PKCE: Web apps, mobile apps
- Client Credentials: Server-to-server
- Device Code: CLI tools, smart TVs

TOKEN HANDLING:
- Short-lived access tokens (15-60 min)
- Refresh tokens for session extension
- Token introspection for validation
- Token revocation endpoint

JWT Best Practices

CLAIMS:
{
  "iss": "https://auth.example.com",
  "sub": "user_123",
  "aud": "api.example.com",
  "exp": 1705320000,
  "iat": 1705316400,
  "scope": "read:users write:users"
}

SECURITY:
- Use asymmetric keys (RS256, ES256)
- Validate all claims
- Check token expiration
- Verify audience matches
- Keep tokens stateless when possible

OpenAPI/Swagger Patterns

Specification Structure

yaml

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  description: API description with markdown support
  contact:
    name: API Support
    url: https://example.com/support

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://api.staging.example.com/v1
    description: Staging

security:
  - bearerAuth: []

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      tags: [Users]
      # ... operation details

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email

Reusable Components

yaml

components:
  schemas:
    # Reusable pagination
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        perPage:
          type: integer

    # Reusable error
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string

  parameters:
    # Reusable query params
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1

  responses:
    # Reusable responses
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Best Practices

Do

Design APIs for consumers, not implementation convenience
Use meaningful HTTP status codes
Provide idempotency keys for non-idempotent operations
Include rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining)
Return Location header for created resources
Support CORS properly for browser clients
Document all error codes with resolution steps
Version your API from day one
Use HTTPS exclusively
Implement request validation with clear error messages

Avoid

Exposing internal implementation details (database IDs, stack traces)
Breaking changes without versioning
Inconsistent naming across endpoints
Deeply nested URLs (more than 2 levels)
Using GET for operations with side effects
Returning different structures for success/error
Ignoring backward compatibility
Over-fetching in GraphQL without limits
Authentication via query parameters (except OAuth callbacks)
Mixing REST and RPC styles in the same API

References

```
templates/rest-api-template.md
```
- REST API specification template
```
templates/graphql-schema-template.md
```
- GraphQL schema template

api-contract-design

NPX Install

Tags

SKILL.md Content

API Design Patterns

When to Use

Core Principles

1. Contract-First Design

2. Consistency Over Cleverness

3. Design for Evolution

REST API Patterns

Resource Modeling

HTTP Method Semantics

Status Code Selection

Error Response Format

Pagination Patterns

Offset-Based (Simple, not for large datasets)

Cursor-Based (Recommended for large datasets)

Filtering and Sorting

GraphQL Patterns

Schema Design Principles

Query Design

Mutation Design

N+1 Query Prevention

API Versioning Strategies

URL Path Versioning

Header Versioning

Query Parameter Versioning

Recommended: Dual Approach

Authentication Patterns

API Keys

OAuth 2.0 / OIDC

JWT Best Practices

OpenAPI/Swagger Patterns

Specification Structure

Reusable Components

Best Practices

Do

Avoid

References