REST API Contract Design

REST API Contract Design

A REST API is a contract between teams that may never speak to each other — the mobile team, the third-party integrator, the frontend team six months from now. Once that contract ships, every inconsistency (an endpoint that returns snake_case next to one that returns camelCase, a DELETE that isn't actually idempotent, an error shape that changes per-endpoint) becomes permanent technical debt that client code has to special-case forever. This guide covers the decisions that make an API predictable enough that consumers can guess the next endpoint correctly before reading the docs.

1. Resource Naming Conventions

Resources are nouns, not actions — the HTTP method already carries the verb. URLs should be plural, hierarchical for genuine ownership, and flat once nesting gets deep.

2. HTTP Methods, Safety, and Idempotency

Two properties matter for every method: safe (doesn't change server state — cacheable, retryable with zero risk) and idempotent (calling it N times has the same effect as calling it once — safe to retry after a timeout).

POST /orders HTTP/1.1
Idempotency-Key: 8f14e45f-ceea-467e-b3b1-9f4c6b2a1234
Content-Type: application/json
 
{"customerId": 42, "items": [{"productId": 101, "quantity": 2}]}

3. Status Codes

Status codes are part of the contract — clients branch on them programmatically, so consistency matters more than cleverness.

4. Pagination: Cursor vs Offset vs Keyset

Three strategies exist, and picking the wrong one for the dataset size is a common LLD/system-design interview trap.

Offset pagination

// GET /orders?limit=20&offset=40
{
  "data": [ { "id": 1041, "status": "SHIPPED" } ],
  "meta": { "limit": 20, "offset": 40, "total": 1834 }
}

Keyset (seek) pagination

// GET /orders?limit=20&after_id=1040
{
  "data": [ { "id": 1041, "status": "SHIPPED" } ],
  "meta": { "limit": 20, "next_after_id": 1060 }
}

Cursor pagination

// GET /orders?limit=20&cursor=eyJpZCI6MTA0MCwidHMiOjE3MjM0NTZ9
{
  "data": [ { "id": 1041, "status": "SHIPPED" } ],
  "meta": {
    "next_cursor": "eyJpZCI6MTA2MCwidHMiOjE3MjM0NjB9",
    "has_more": true
  }
}

The cursor is an opaque, server-generated, base64-encoded token (typically encoding the last-seen sort key plus tiebreaker) — the client never constructs or parses it, which lets the server change the encoding later without breaking clients.

5. Filtering, Sorting, and Partial Responses

GET /orders?status=SHIPPED&createdAfter=2026-01-01&sort=-createdAt,status&fields=id,status,total

6. Standardized Error Response Format

Every error, from every endpoint, should have the same envelope shape so client error-handling code is written once.

{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "No order exists with id 9981.",
    "details": [
      { "field": "orderId", "issue": "does not exist" }
    ],
    "traceId": "6b1f0c2e-4a3d-4e91-9c2a-1f7e6d5b8a90"
  }
}

7. API Versioning

Whichever strategy you pick, prefer additive, backward-compatible changes within a version (new optional fields, new endpoints) and reserve a version bump for actual breaking changes (removing/renaming a field, changing a field's type, changing required-ness).

8. HATEOAS (Briefly)

Hypermedia As The Engine Of Application State: responses include links to the next valid actions, so clients don't hardcode URL construction.

{
  "id": 1041,
  "status": "PENDING",
  "_links": {
    "self": { "href": "/orders/1041" },
    "cancel": { "href": "/orders/1041/cancel", "method": "POST" },
    "customer": { "href": "/customers/42" }
  }
}

9. OpenAPI: Contract-First vs Code-First

Code-first: write the handler/controller code, generate the OpenAPI spec from annotations. Fast to start, but the "contract" is a byproduct that can drift subtly across refactors.

Contract-first: write the OpenAPI YAML spec first, generate/validate server stubs and client SDKs from it, implement handlers against the generated interface. Slower to start, but the contract is the source of truth, reviewable in a PR before any code exists, and multiple teams (backend, frontend, QA) can work in parallel against a stable, agreed-upon shape.

openapi: 3.0.3
info:
  title: Orders API
  version: "1.0.0"
paths:
  /orders/{orderId}:
    get:
      summary: Fetch a single order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Order:
      type: object
      required: [id, status, total]
      properties:
        id:
          type: integer
        status:
          type: string
          enum: [PENDING, SHIPPED, CANCELLED]
        total:
          type: number
          format: decimal
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string

10. Rate Limiting Headers

Rate limits are part of the contract too — well-behaved clients need to know how close they are to a limit without guessing.

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1723459200

HTTP/1.1 429 Too Many Requests
Retry-After: 30

11. Caching with ETags and Conditional Requests

REST gets HTTP caching for free — an underused piece of the contract that avoids re-sending unchanged data.

GET /orders/1041 HTTP/1.1
 
HTTP/1.1 200 OK
ETag: "a1b2c3d4"
Cache-Control: private, max-age=60

A subsequent request can send the ETag back and let the server short-circuit to a 304 when nothing changed:

GET /orders/1041 HTTP/1.1
If-None-Match: "a1b2c3d4"
 
HTTP/1.1 304 Not Modified

The same ETag mechanism also solves optimistic concurrency for writes — a PUT/PATCH that includes If-Match fails with 412 Precondition Failed if the resource changed since the client last read it, preventing a lost-update race between two concurrent editors.

PUT /orders/1041 HTTP/1.1
If-Match: "a1b2c3d4"
 
HTTP/1.1 412 Precondition Failed

12. Bulk Operations and Long-Running (Async) Requests

Not every operation fits the request-response-in-milliseconds shape. Two patterns cover the common exceptions.

Bulk operations

// POST /orders/bulk
{
  "operations": [
    { "method": "PATCH", "orderId": 1041, "body": { "status": "SHIPPED" } },
    { "method": "PATCH", "orderId": 1042, "body": { "status": "CANCELLED" } }
  ]
}

// 207 Multi-Status — each sub-operation reports its own outcome independently
{
  "results": [
    { "orderId": 1041, "status": 200 },
    { "orderId": 1042, "status": 404, "error": { "code": "ORDER_NOT_FOUND", "message": "..." } }
  ]
}

A bulk endpoint should never be all-or-nothing by default unless the client explicitly opts into transactional semantics — partial success with a per-item status is usually the more useful contract, since one bad ID in a batch of 500 shouldn't fail the other 499.

Long-running operations

An operation that can't complete within a normal request timeout (a large export, an async ML inference job) returns 202 Accepted immediately with a handle to poll or a webhook callback, rather than blocking the connection.

// POST /reports  ->  202 Accepted
{
  "operationId": "op_8f14e45f",
  "status": "PROCESSING",
  "_links": { "self": { "href": "/operations/op_8f14e45f" } }
}

// GET /operations/op_8f14e45f  (poll until done)
{
  "operationId": "op_8f14e45f",
  "status": "COMPLETE",
  "result": { "href": "/reports/rep_9931" }
}

Interview Questions

• What's the difference between a "safe" HTTP method and an "idempotent" one? Give an example of a method that's idempotent but not safe.
• How would you prevent a client's retried POST /orders from creating a duplicate order after a network timeout?
• Compare offset, keyset, and cursor pagination. At what scale does offset pagination start to break down, and why?
• Design a standardized error response shape. Why should clients branch on an error code field instead of the message field?
• Compare URL-path, header-based, and content-negotiation API versioning. Which would you pick for a public API and why?
• What is HATEOAS, and why do most production REST APIs not fully implement it despite it being part of the original REST constraints?
• What's the difference between contract-first and code-first API design? When does contract-first's extra upfront cost pay off?
• Why does nesting resources more than 1-2 levels deep (/a/{id}/b/{id}/c/{id}/d) tend to become a design smell?
• How does an ETag with If-Match on a write prevent a lost-update race between two concurrent clients editing the same resource?
• Design a bulk-update endpoint for 500 resources at once. Should a single bad item fail the whole batch? Justify your answer.
• How would you design an endpoint for an operation that takes 10 minutes to complete? Why not just hold the HTTP connection open?