API Design

What it is

API design is the discipline of creating programmatic interfaces that are clear, consistent, and evolvable. A well-designed API acts as a contract between systems, defining how consumers can interact with a service in a predictable and reliable manner.

Effective API design goes beyond simply exposing functionality. It requires considering developer experience, long-term system evolution, and integration with architectural patterns like microservices and API Gateway. A well-designed API reduces adoption friction, minimizes integration errors, and enables teams to work independently.

The design process should be iterative and user-centered, starting with contract definition before implementation — an approach known as API-first that aligns with spec-driven development.

Architectural styles

OpenAPI specification

An OpenAPI specification defines a REST API contract declaratively. Example for a users endpoint:

openapi: 3.0.3
info:
  title: User Management API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/CursorPagination'
components:
  schemas:
    User:
      type: object
      required: [id, email, created_at]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time
    CursorPagination:
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean

Versioning strategies

Pagination patterns

Cursor-based (recommended)

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "limit": 20
  }
}

Advantages: Consistent with changing data, efficient for large datasets Disadvantages: Cannot jump to specific pages

Offset-based

{
  "data": [...],
  "pagination": {
    "offset": 40,
    "limit": 20,
    "total": 1250,
    "has_more": true
  }
}

Advantages: Familiar, allows direct navigation Disadvantages: Inconsistent with insertions/deletions, inefficient on large datasets

Error response standards

Following RFC 9457 (Problem Details for HTTP APIs), which replaces RFC 7807:

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request body contains invalid data",
  "instance": "/users/create",
  "errors": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "Email must be a valid email address"
    }
  ],
  "trace_id": "abc123def456"
}

Rate limiting design

Common strategies

Response headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 742
X-RateLimit-Reset: 1640995200
Retry-After: 3600

Security and authentication

Integration with OAuth/OIDC is fundamental for modern APIs. Key considerations:

• Bearer tokens for stateless authentication
• Granular scopes for specific authorization
• Mandatory HTTPS in production
• Input validation on all endpoints
• Rate limiting per user/IP

Integrated observability

APIs should integrate natively with observability:

• Trace IDs in response headers
• Latency metrics per endpoint
• Structured logs with request context
• Standardized health checks (/health, /ready)

Why it matters

A poorly designed API becomes permanent technical debt. Every design decision — resource naming, response structure, error handling — solidifies once there are consumers in production. Changing a public API requires versioning, client migration, and coordination between teams.

The cost of redesigning an API after launch is exponentially higher than investing in initial design. A well-designed API reduces integration time from weeks to days, minimizes support tickets, and enables product teams to move faster. In organizations with multiple teams, consistent APIs reduce cognitive load and enable reuse of tools and patterns.

References

• API Design Patterns — JJ Geewax, Manning, 2021. Proven patterns for API design.
• OpenAPI Specification 3.1.0 — OpenAPI Initiative, 2021. Standard for REST API specification.
• RFC 9457: Problem Details for HTTP APIs — IETF, 2023. Current standard for structured error responses (replaces RFC 7807).
• Google API Design Guide — Google, 2024. Comprehensive guide to API best practices.
• REST API Design Rulebook — Mark Masse, O'Reilly, 2011. Fundamental REST design principles.
• Build APIs You Won't Hate — Phil Sturgeon, 2015. Practical guide to developer-centered API design.