API Design

Overview

APIs are contracts. Broken contracts break everyone downstream. Fixing a shipped API is ten times harder than designing it right.

Core principle: DESIGN THE API CONTRACT BEFORE IMPLEMENTING THE HANDLER. Implementation details leak into APIs when you code first.

Violating the letter of this process is violating the spirit of API design.

The Iron Law

DESIGN THE API CONTRACT BEFORE IMPLEMENTING THE HANDLER

If you haven't written the OpenAPI spec (or equivalent contract), you cannot write handler code.

When to Use

Always:

New REST endpoints
New GraphQL types/queries/mutations
Modifying existing API contracts
Adding authentication/authorization
Designing inter-service communication
Building public or partner-facing APIs

Use this ESPECIALLY when:

Under pressure to "just ship the endpoint"
The database schema already exists and is pulling you toward a data-dump API
Multiple consumers will use the API
You're designing something that will be versioned

Don't skip when:

It's an internal API ("internal today, public tomorrow")
Only one consumer exists right now ("they always multiply")
It's a simple CRUD endpoint ("simple endpoints set patterns for complex ones")

Phase 1: Resource Modeling

BEFORE touching URLs or HTTP methods:

Identify Resources, Not Actions
- Resources are nouns: users, orders, invoices
- NOT verbs: getUser, createOrder, sendInvoice
- If you can't name it as a noun, rethink the model
Map Relationships
- Parent-child: /users/{id}/orders
- Limit nesting to 2 levels maximum
- Deeper than 2? Use top-level resource with filter: /orders?user_id=123
Define Resource Representations
- What fields does each resource have?
- What's required vs optional?
- What are the data types and constraints?
- Write it down BEFORE coding anything
Distinguish Collection vs Instance
- Collection: /orders (list, create)
- Instance: /orders/{id} (get, update, delete)
- Every resource needs both unless there's a reason not to

Phase 2: URL Design and HTTP Semantics

URLs are the backbone of your API. Get them right.

URL Conventions

Rule	Good	Bad
Plural nouns	`/users`, `/orders`	`/user`, `/order`
Kebab-case	`/line-items`	`/lineItems`, `/line_items`
No verbs	`/orders` + POST	`/createOrder`
No trailing slash	`/users`	`/users/`
Lowercase only	`/users/{id}/orders`	`/Users/{ID}/Orders`

HTTP Methods

Use methods correctly. They have semantics. Respect them.

Method	Purpose	Idempotent	Safe	Example
GET	Read resource(s)	Yes	Yes	`GET /orders/123`
POST	Create resource	No	No	`POST /orders`
PUT	Full replace	Yes	No	`PUT /orders/123`
PATCH	Partial update	Yes	No	`PATCH /orders/123`
DELETE	Remove resource	Yes	No	`DELETE /orders/123`

POST is not a catch-all. If you're using POST for everything, you're building RPC, not REST.

Actions that don't fit CRUD:

Use sub-resources: POST /orders/123/cancel
Or use a "command" resource: POST /order-cancellations
Never: POST /cancelOrder

Status Codes

Use them. Use the RIGHT ones.

Code	Meaning	When
200	OK	Successful GET, PUT, PATCH, DELETE
201	Created	Successful POST that created a resource
204	No Content	Successful DELETE with no body
400	Bad Request	Validation error, malformed input
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	Syntactically valid but semantically wrong
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server bug (never intentional)

Don't return 200 with { "error": "something failed" }. That's lying to HTTP clients.

Versioning

Version from day one. Not "when we need it."

Preferred: URL path versioning

/v1/users
/v2/users

Acceptable: Header versioning

Accept: application/vnd.myapi.v2+json

Unacceptable: No versioning You WILL break clients. It's a matter of when, not if.

Phase 3: Request/Response Schema Design

Consistency is more important than cleverness.

Response Envelope

Pick ONE envelope format. Use it EVERYWHERE.

{
  "data": { ... },
  "meta": {
    "request_id": "abc-123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

For collections:

{
  "data": [ ... ],
  "meta": {
    "request_id": "abc-123",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "pagination": {
    "total": 142,
    "page": 2,
    "per_page": 20,
    "next_cursor": "eyJpZCI6MTIzfQ=="
  }
}

Error Format

ONE error format. Consistent across ALL endpoints.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "INVALID_FORMAT"
      }
    ]
  },
  "meta": {
    "request_id": "abc-123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Never return:

Plain strings as error bodies
Different error shapes from different endpoints
Stack traces to clients (log them server-side)
Generic "Something went wrong" without a request ID

Pagination

Cursor-based for large/real-time datasets:

GET /orders?cursor=eyJpZCI6MTIzfQ==&limit=20

Offset-based for small, stable datasets:

GET /orders?page=2&per_page=20

Always include: total count, current page/cursor, next page/cursor, per-page limit.

Always set a maximum per_page. Unbounded queries kill databases.

Field Naming

Use snake_case for JSON fields (most common convention)
Be consistent: don't mix createdAt and updated_at
Use ISO 8601 for dates: 2024-01-15T10:30:00Z
Use strings for IDs (even if numeric internally)

Phase 4: Authentication and Authorization

Security is not optional. Design it in from the start.

Authentication Patterns

Pattern	Use When
OAuth 2.0 + JWT	User-facing APIs, third-party access
API Keys	Server-to-server, simple integrations
mTLS	Internal service mesh, high security

API Keys:

Pass in header: Authorization: Bearer <key> or X-API-Key: <key>
NEVER in URL query parameters (they get logged)
Rotate regularly, support multiple active keys

JWT:

Short-lived access tokens (15 min)
Longer-lived refresh tokens
Include minimal claims (user ID, roles)
Validate signature, expiry, issuer on EVERY request

Authorization

Check permissions at the resource level, not just the endpoint
GET /users/123/orders must verify caller can access user 123's orders
Return 403 for "authenticated but not allowed," 404 if you don't want to reveal existence

Rate Limiting

Design it in. Don't bolt it on.

Headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1705312200

Per-client, not global
Different tiers for different endpoints (reads vs writes)
Return 429 with Retry-After header

Phase 5: Contract Specification

Write the OpenAPI spec BEFORE the handler.

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
paths:
  /v1/orders:
    get:
      summary: List orders
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

The spec is the source of truth. Generate types, validators, and documentation from it. Don't write them by hand.

GraphQL Considerations

When using GraphQL instead of REST:

Design the schema as a graph, not a set of REST endpoints
Use connections pattern for pagination (edges, nodes, pageInfo)
Implement DataLoader for N+1 prevention
Limit query depth and complexity
Separate queries (reads) from mutations (writes)
Use input types for mutation arguments

type Query {
  order(id: ID!): Order
  orders(first: Int, after: String, filter: OrderFilter): OrderConnection!
}

type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

Phase 6: Discoverability and HATEOAS

Good APIs tell you what you can do next.

Include relevant links in responses:

{
  "data": {
    "id": "order-123",
    "status": "pending",
    "links": {
      "self": "/v1/orders/order-123",
      "cancel": "/v1/orders/order-123/cancel",
      "items": "/v1/orders/order-123/items",
      "customer": "/v1/customers/cust-456"
    }
  }
}

At minimum, include self links. Full HATEOAS when clients need to discover transitions.

Phase 7: Backward Compatibility and Deprecation

Breaking changes are trust violations.

What's Breaking

Removing a field from response
Removing an endpoint
Changing a field's type
Making an optional field required
Changing URL structure
Changing error codes/formats

What's Not Breaking

Adding a new field to response
Adding a new endpoint
Adding a new optional parameter
Adding a new error code (if clients handle unknown codes)

Deprecation Process

Mark deprecated in spec and docs
Add Sunset header with removal date
Log usage of deprecated endpoints
Contact consumers directly
Maintain for minimum 6 months (12 for public APIs)
Remove only after usage drops to zero

Sunset: Sat, 15 Jun 2025 00:00:00 GMT
Deprecation: true
Link: </v2/users>; rel="successor-version"

Never silently remove endpoints. Ever.

Red Flags - STOP and Revisit Design

If you catch yourself:

Writing handler code without a spec
Using verbs in URLs
Returning 200 for errors
Building different error formats per endpoint
Adding query parameters to control response shape extensively
Nesting URLs more than 2 levels deep
Skipping versioning "for now"
Exposing database column names as API fields
Returning different field names for the same concept
Adding authentication "later"

ALL of these mean: STOP. Return to Phase 1.

Common Rationalizations

Excuse	Reality
"Internal API, doesn't need design"	Internal APIs become external. Design it right from the start.
"Just one endpoint, don't need versioning"	One endpoint becomes twenty. Version from day one.
"We'll add auth later"	Unauthenticated APIs get abused. Security from the start.
"Database schema drives the API"	Database is implementation. API is contract. They're different.
"POST for everything is simpler"	POST for everything is RPC. You lose HTTP semantics and caching.
"Error format doesn't matter yet"	Inconsistent errors multiply. Fix on day one or fix forever.
"Breaking change is fine, we control the client"	You control it today. Tomorrow you won't.
"Spec is overhead, code is the spec"	Code drifts. Spec is the source of truth.
"HATEOAS is over-engineering"	At minimum, include self links. Clients need discoverability.
"Pagination can wait"	Unbounded queries will take down your database. Paginate from the start.

Quick Reference

Phase	Key Activities	Success Criteria
1. Resource Modeling	Identify nouns, map relationships	Resources are clear, no verbs
2. URL Design	Define paths, methods, status codes	Consistent, RESTful, versioned
3. Schema Design	Envelope, errors, pagination, naming	One format everywhere
4. Auth	Authentication, authorization, rate limits	Security designed in
5. Contract Spec	OpenAPI/GraphQL schema	Spec exists before code
6. Discoverability	Links, HATEOAS	Clients can navigate the API
7. Compatibility	Deprecation plan, breaking change rules	No surprise breakage

Verification Checklist

Before implementing any handler:

Can't check all boxes? You're not ready to write handler code.

Integration with Other Skills

This skill integrates with:

test-driven-development - Write contract tests from the spec BEFORE implementing handlers. The spec is your test oracle.
documentation-generation - Generate API docs from the OpenAPI spec. The spec IS the documentation source.

Complementary skills:

systematic-debugging - When API behavior doesn't match the contract, debug systematically
defense-in-depth - Validate inputs at API boundary AND service layer

Final Rule

API spec → contract tests → handler implementation
Otherwise → not API design

No handler code without a contract. No exceptions without your human partner's permission.

api-design