How APIs Use JSON: Requests, Responses and Conventions
Most HTTP APIs send and receive JSON. The format itself is simple, but a few conventions around it decide whether an API is pleasant or frustrating to use. This guide covers what you will see on the wire and the patterns worth following.
Headers that matter
A client sending JSON sets Content-Type: application/json, and a client that wants JSON back sends Accept: application/json. Many frameworks only parse a request body as JSON when the Content-Type header says so, which is a common cause of "empty body" bugs.
POST /v1/orders HTTP/1.1
Content-Type: application/json
Accept: application/json
{"sku": "A-1", "quantity": 2}Response bodies
Responses usually return an object, even for lists, because an object can grow new fields later without breaking clients:
{
"data": [ { "id": "o_1", "status": "paid" } ],
"next_cursor": "eyJpZCI6Im9fMSJ9"
}Wrapping the list in data leaves room for pagination and metadata.
Error responses
Return an appropriate HTTP status code and a JSON body that explains the error. RFC 9457 ("Problem Details for HTTP APIs") defines a standard shape with the media type application/problem+json:
{
"type": "https://api.shop.test/errors/out-of-stock",
"title": "Item out of stock",
"status": 409,
"detail": "SKU A-1 has 0 units available."
}Pagination
Large collections are returned in pages. Offset pagination (?offset=40&limit=20) is simple but can skip or repeat items when data changes. Cursor pagination returns an opaque token for the next page, often Base64-encoded, which stays stable as data changes.
Conventions worth following
- Dates: ISO 8601 strings in UTC, such as
"2026-10-03T09:15:00Z". - IDs: strings, even when numeric, so large values do not lose precision in JavaScript.
- Money: integer minor units (
"amount": 1999for 19.99) or decimal strings, never binary floating point. - Key style: pick
snake_caseorcamelCaseand use it everywhere. - Nulls: decide whether missing and null mean different things, and document it.
Streaming and large results
For exports and event streams, many APIs use NDJSON: one JSON object per line, so clients can process records as they arrive instead of waiting for one huge array.
Debugging API JSON
Copy a response into the JSON Formatter to read it, the JSON Viewer to explore large responses, and JSON Compare to see what changed between two calls. Generate client types with JSON to TypeScript.
Frequently asked questions
Should an API return a top-level array?
It is valid JSON, but returning an object lets you add pagination and metadata later without breaking clients.
Why do some APIs send numbers as strings?
To avoid precision loss for large integers and to keep exact decimal values for money.
What status code should a JSON validation error use?
400 Bad Request for malformed JSON, and often 422 Unprocessable Content when the JSON is valid but the data fails validation.