response-design-and-pagination

Responses Are Contracts, Not Accidents

Every response your API returns is a contract. The moment a client parses it, the shape is frozen. Get it wrong and you carry the debt forever. Get it right -- consistent envelopes, stable pagination, predictable expand behavior -- and your API becomes a platform developers trust with production traffic.

Response design drives SDK generation, backward compatibility, and client-side caching. A well-structured response eliminates round trips, prevents breaking changes, and makes your API feel like a native library in every language.

Single Resource Envelope

Return the full object on create and update. Always.

A POST that returns { "id": 42 } forces a second GET to see what was created. A PATCH that returns 204 No Content leaves the client guessing about server-side side effects like updated_at changes and computed defaults.

Rules:

• POST (201 Created): return the full resource plus a Location header
• PUT/PATCH (200 OK): return the full updated resource
• DELETE: return 204 No Content or 200 OK with a deletion confirmation object
• Include created_at and updated_at timestamps on every resource -- clients need them for display, sorting, and cache invalidation

The resource shape must be identical everywhere it appears -- in a GET, in a list, embedded in another resource, or returned from a mutation. If a compact form is needed, offer ?fields=id,name rather than returning a different shape by default.

List Envelope

Wrap every list response in a consistent envelope. Never return a naked top-level array.

Use this structure for every list endpoint:

{
  "data": [
    { "id": "ord_01HXK3GJ5V", "status": "shipped", "created_at": "2026-01-15T10:30:00Z" },
    { "id": "ord_01HXK3GJ6W", "status": "pending", "created_at": "2026-01-14T08:15:00Z" }
  ],
  "has_more": true,
  "next_cursor": "ord_01HXK3GJ6W"
}

Why this works:

• data is always an array. Clients never check the type.
• has_more is a boolean that maps directly to "Load more" and "Show next page" UIs.
• next_cursor provides the opaque position marker for the next request.
• No total_count by default. Counting millions of rows is expensive and usually unnecessary. Offer it as an opt-in parameter (?include_count=true) when clients explicitly need it.