API Design

Design, review, and document REST and GraphQL APIs. Covers resource naming, HTTP method selection, pagination, filtering, error responses, authentication, rate limiting, versioning, and OpenAPI/GraphQL schema generation.

Workflow

Step 1: Understand the Domain

Before designing endpoints, understand the data model and use cases:

• Identify resources: What are the core entities? (users, orders, products, etc.)
• Map relationships: How do resources relate? (one-to-many, many-to-many)
• List operations: What actions do consumers need? (CRUD, search, aggregate, bulk)
• Identify consumers: Who calls this API? (frontend, mobile, third-party, internal services)
• Check existing patterns: If the project has existing APIs, read them to maintain consistency.

Look at existing code:

• Read route/controller files for current endpoint patterns.
• Check for API documentation (OpenAPI spec, Swagger UI, GraphQL schema).
• Review middleware for auth, validation, rate limiting.

Step 2: REST API Design

Resource Naming Conventions:

• Use plural nouns for collections: /users, /orders, /products
• Use resource IDs for individual items: /users/{userId}
• Nest related resources: /users/{userId}/orders
• Limit nesting to 2 levels max: /users/{userId}/orders/{orderId}
• Use kebab-case for multi-word resources: /order-items, /shipping-addresses
• Use query parameters for filtering, not path segments: /orders?status=pending

HTTP Method Selection:

Pagination (choose one pattern):

Offset-based (simple, allows page jumping):

GET /orders?page=2&per_page=20
Response headers: X-Total-Count: 142, Link: <...>; rel="next"

Cursor-based (stable, better for real-time data):

GET /orders?cursor=eyJpZCI6MTAwfQ&limit=20
Response: { "data": [...], "next_cursor": "eyJpZCI6MTIwfQ", "has_more": true }

Keyset-based (performant for large datasets):

GET /orders?after_id=100&limit=20

Filtering and Sorting:

GET /orders?status=pending&created_after=2024-01-01&sort=-created_at,+total
GET /products?category=electronics&price_min=10&price_max=100
GET /users?search=john&fields=id,name,email

Error Response Format (RFC 7807 Problem Details):

{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The request body contains invalid fields.",
  "instance": "/orders/create",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "code": "INVALID_FORMAT"
    }
  ]
}

Standard HTTP Status Codes:

• 200 OK — Successful read or update
• 201 Created — Successful creation (include Location header)
• 204 No Content — Successful deletion
• 400 Bad Request — Malformed request syntax
• 401 Unauthorized — Missing or invalid authentication
• 403 Forbidden — Authenticated but not authorized
• 404 Not Found — Resource does not exist
• 409 Conflict — State conflict (duplicate, version mismatch)
• 422 Unprocessable Entity — Validation errors
• 429 Too Many Requests — Rate limit exceeded (include Retry-After header)
• 500 Internal Server Error — Unexpected server failure

Step 3: GraphQL API Design

Schema Design:

type Query {
  user(id: ID!): User
  users(filter: UserFilter, pagination: PaginationInput): UserConnection!
  order(id: ID!): Order
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!
}

type User {
  id: ID!
  email: String!
  name: String!
  orders(first: Int, after: String): OrderConnection!
  createdAt: DateTime!
}

input CreateUserInput {
  email: String!
  name: String!
}

type CreateUserPayload {
  user: User
  errors: [UserError!]!
}

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

GraphQL Best Practices:

• Use Relay-style connections for paginated lists (edges, nodes, pageInfo).
• Use input types for mutations, payload types for responses.
• Return errors in the payload, not as GraphQL errors (reserve those for system failures).
• Implement DataLoader for N+1 prevention.
• Set query depth and complexity limits to prevent abuse.
• Use enums for finite sets of values.

Step 4: Authentication and Rate Limiting

Authentication patterns:

• API Keys: Simple, best for server-to-server. Send in Authorization: Bearer <key> or X-API-Key header.
• JWT: Stateless, best for user sessions. Short-lived access tokens + refresh tokens.
• OAuth 2.0: Best for third-party integrations. Use authorization code flow with PKCE for public clients.

Rate Limiting:

• Return rate limit info in headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
• Use 429 Too Many Requests with Retry-After header.
• Apply different limits per endpoint sensitivity (login stricter than read).
• Use sliding window or token bucket algorithms.

Step 5: Versioning Strategy

• URL path versioning: /v1/users, /v2/users — most common, clear, easy to route.
• Header versioning: Accept: application/vnd.api+json; version=2 — cleaner URLs, harder to test.
• Query parameter: /users?version=2 — easy to test, pollutes query string.

Recommended approach: URL path versioning with a deprecation policy.

Step 6: Documentation

Generate OpenAPI 3.0 specification:

openapi: 3.0.3
info:
  title: <API Name>
  version: 1.0.0
  description: <description>
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

Output Format

## API Design

### Resources
| Resource | Endpoints | Description |
|----------|-----------|-------------|
| <name> | <count> | <purpose> |

### Endpoints

#### <METHOD> <path>
**Purpose**: <what it does>
**Auth**: <required | optional | public>
**Request**:
```json
<example request body>

Response (200):

<example response body>

Errors: <list of possible error codes>

Authentication

Pagination

Rate Limiting

<limits per tier/endpoint>

Versioning

Examples

User: "Design a REST API for an e-commerce platform" Action: Identify resources (users, products, orders, cart), design endpoints for each, define pagination, error format, auth strategy, and produce an OpenAPI spec.

User: "Should I use REST or GraphQL for my mobile app?" Action: Compare both approaches considering mobile-specific needs (bandwidth, flexibility, caching), recommend based on the use case.

User: "Review my API endpoints for consistency" Action: Read existing routes, check naming conventions, HTTP method usage, error responses, and pagination patterns. Report inconsistencies with fixes.

User: "Add pagination to my list endpoints" Action: Assess the data characteristics, recommend cursor vs offset pagination, provide implementation code and response format.

Best Practices

• Be consistent. If one endpoint uses snake_case, all endpoints should. If one returns errors in a certain format, all should.
• Design for the consumer, not the database. API resources do not need to mirror database tables.
• Use HTTP methods correctly. GET should never have side effects. DELETE should be idempotent.
• Always return the created/updated resource in POST/PUT/PATCH responses. Saves the client a round trip.
• Version from day one. Adding versioning later is painful.
• Provide _links or Link headers for discoverability (HATEOAS) on public APIs.
• Use ETag and If-None-Match for conditional requests to reduce bandwidth.
• Design idempotency into write operations using Idempotency-Key headers for payment or order APIs.
• Keep endpoint count manageable. If you have 200 endpoints, you likely need to rethink your resource model.
• Document every endpoint, including error responses. Consumers cannot use what they cannot understand.