← Back to Guides

JSON API Format: Request Payloads, Headers, and Response Schemas

Deep dive into JSON API structures: envelopes vs raw arrays, standard error schemas, pagination meta keys, and Content-Type negotiation.

JavaScript Object Notation (JSON) is the dominant data serialization format for web APIs. However, inconsistent JSON structures cause friction for frontend developers. Establishing clean response conventions transforms an average API into an extraordinary developer experience.

Standard JSON Response Envelope Pattern

Wrapping payloads in a predictable envelope allows client libraries to inspect status and metadata without guessing:

{
  "success": true,
  "data": [
    { "id": 101, "title": "TypeScript Handbook" },
    { "id": 102, "title": "Designing Data-Intensive Applications" }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "totalCount": 84,
    "totalPages": 5
  }
}

Always serve JSON with Content-Type: application/json; charset=utf-8 and parse requests defensively using schemas like Zod or Joi.