Quick answer: Send and return JSON with
Content-Type: application/json, wrap collections in adataobject rather than a bare array, and let the HTTP status code carry success or failure while the body carries the details. Use a structured error object with a machine-readablecode, pick offset or cursor pagination based on dataset size, and version breaking changes in the URL path (/api/v2/). Keep naming, date formats, andnullhandling consistent across every endpoint.
JSON became the default format for REST APIs not because anyone mandated it, but because it solved the right problems at the right time. It is lightweight compared to XML, native to JavaScript (the language of the web), and human-readable enough that you can glance at a response and understand the data without special tooling.
Today, the biggest APIs on the internet - GitHub, Stripe, Twilio, OpenAI - all speak JSON. But returning a JSON blob from an endpoint is the easy part. The hard part is doing it correctly: structuring responses consistently, paginating large collections, handling errors gracefully, and keeping your data secure. That is what this post covers.
Explore the resulting JSON in the JSON Viewer, or select nested fields with the JSONPath Query Tester.
For Go handlers, the Go JSON decoder tests demonstrate how encoding/json handles request boundaries and colliding field names.
Content-Type Headers Matter
When you send JSON in an HTTP request, set the Content-Type header to application/json so the server knows how to parse the body. When you receive JSON, the server should return the same content type. The Accept header tells the server what format you want back - some APIs support multiple formats and use this header to decide which one to return:
const response = await fetch("/api/users", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify({ name: "Alice", role: "admin" })
});
If you leave out the Accept header, most modern APIs default to JSON, but it is good practice to be explicit. Middleware, proxies, and client libraries all rely on these headers to decide how to handle the body. The header has more subtleties than it looks (charset parameters, the +json suffix for vendor types, what happens when it is missing), which we cover in the JSON Content-Type and MIME type guide. For the client side of this exchange, see how to fetch JSON in JavaScript.
Structuring JSON Responses
There is no universal standard for JSON response structure, but certain conventions are widely adopted. For a single resource, return its fields directly:
{
"id": 42,
"name": "Alice Chen",
"email": "alice@example.com",
"role": "admin",
"createdAt": "2025-03-15T08:30:00Z"
}
For a collection of resources, wrap the array in an object. Returning a bare array as the top-level response is generally avoided because it makes it harder to add metadata later, and historically had JSON hijacking implications:
{
"data": [
{ "id": 1, "name": "Alice" },
{ "id": 2, "name": "Bob" }
],
"meta": {
"total": 47,
"page": 1,
"perPage": 20
}
}
Wrapping collections in a data key gives you room to add meta, pagination, or links without breaking existing clients.
HTTP Status Codes and JSON
Before placing API responses behind a browser cache, proxy, or CDN, review seven JSON API caching mistakes that serve stale or private data.
Clients that automate retries should review seven JSON API rate-limit mistakes that trigger more 429 errors, including Retry-After, jitter, shared concurrency, pagination checkpoints, and retry deadlines.
For mutating requests that may be retried after a timeout, review seven JSON API idempotency mistakes that create duplicate orders before adding automatic retry logic.
The HTTP status code and the JSON body should tell a consistent story. Here are the most common pairings:
- 200 OK - successful GET, PUT, or PATCH. Return the resource. (For partial updates, the body format of a PATCH request is its own topic; see JSON Patch vs JSON Merge Patch.)
- 201 Created - successful POST that created a resource. Return the created resource with its new ID.
- 204 No Content - successful DELETE. No JSON body at all.
- 400 Bad Request - the JSON body was malformed or failed validation.
- 401 Unauthorized - missing or invalid authentication.
- 404 Not Found - the resource does not exist.
- 422 Unprocessable Entity - the JSON was valid, but the data did not pass business rules.
- 500 Internal Server Error - something broke server-side.
A common anti-pattern is returning a 200 status code with an error message inside the JSON body. This forces clients to check both the status code and the body to determine if the request succeeded. Use the correct HTTP status code and reserve the body for details - do not mix the two.
Error Response Formats
A well-structured error response should include enough detail for the client to understand what went wrong and how to fix it:
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Request body failed validation",
"details": [
{
"field": "email",
"message": "Must be a valid email address"
},
{
"field": "age",
"message": "Must be a positive integer"
}
]
}
}
The code field gives clients a machine-readable identifier they can match on. The message field is human-readable. The details array breaks down field-level issues so clients can highlight specific form inputs.
RFC 7807 ("Problem Details for HTTP APIs") is gaining traction as a standardized approach. It defines fields like type, title, status, detail, and instance. Worth considering if you are designing a new API from scratch. We compare the custom envelope above against Problem Details and other conventions in JSON API error response formats.
Pagination Patterns
For a production-focused checklist covering ordering, cursor integrity, navigation links, limits, termination, and concurrent writes, see eight JSON API pagination mistakes that cause missing or duplicate data.
Three pagination strategies are common in JSON APIs, each with different tradeoffs:
Offset-based pagination is the simplest. The client sends page and perPage (or offset and limit) query parameters:
GET /api/users?page=3&perPage=20
{
"data": [...],
"pagination": {
"page": 3,
"perPage": 20,
"total": 247,
"totalPages": 13
}
}
The downside is that offset queries get slower on large tables and inserting or deleting rows between requests can cause items to be skipped or duplicated.
Cursor-based pagination is better for large or frequently-changing datasets. Instead of a page number, the client sends a cursor - usually an opaque token or the last item's ID:
GET /api/events?cursor=eyJpZCI6MTAwfQ&limit=50
{
"data": [...],
"pagination": {
"nextCursor": "eyJpZCI6MTUwfQ",
"hasMore": true
}
}
Cursor pagination is more performant at scale and immune to the row-shift problem, but clients cannot jump to an arbitrary page.
Link-header pagination puts navigation URLs in the HTTP Link header rather than the JSON body. GitHub's API uses this approach. It keeps the response body clean but requires clients to parse the header.
Nested vs. Flat Structures
Should related resources be nested inline or referenced by ID? Both approaches have tradeoffs:
// Nested - fewer requests, but potentially large payloads
{
"id": 1,
"title": "My Post",
"author": {
"id": 42,
"name": "Alice",
"avatar": "https://..."
},
"comments": [
{ "id": 100, "body": "Great post!", "author": { "id": 43, "name": "Bob" } }
]
}
// Flat - smaller payloads, but requires additional requests
{
"id": 1,
"title": "My Post",
"authorId": 42,
"commentIds": [100, 101, 102]
}
The middle ground that many APIs settle on: include one level of nesting for commonly-needed related data and use IDs for everything else. Some APIs let clients choose through query parameters like ?include=author,comments or GraphQL-style field selection.
API Versioning
Before changing a production contract, review seven JSON API versioning mistakes that break client integrations, covering breaking changes, explicit selection, deprecation, schemas, SDKs, and retirement.
When your JSON response structure changes in a breaking way, you need versioning. The three main approaches:
- URL path versioning:
/api/v2/users- the most common and most visible approach. - Header versioning:
Accept: application/vnd.myapi.v2+json- cleaner URLs but harder to test in a browser. - Query parameter:
/api/users?version=2- simple but easy to forget.
URL path versioning is the most widely adopted because it is explicit, easy to route on the server, and obvious in documentation. Whichever you choose, document it clearly and give clients a migration window before removing old versions.
Practical Example
Here is a realistic createUser function demonstrating proper headers, error handling, and response parsing:
async function createUser(userData) {
const response = await fetch("https://api.example.com/v1/users", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer " + token
},
body: JSON.stringify(userData)
});
// Handle specific error cases
if (response.status === 422) {
const body = await response.json();
throw new ValidationError(body.error.details);
}
if (response.status === 401) {
throw new AuthError("Token expired or invalid");
}
if (!response.ok) {
const body = await response.json().catch(() => null);
throw new ApiError(response.status, body?.error?.message ?? "Unknown error");
}
// 201 Created - return the new user
return response.json();
}
Notice the pattern: check for specific status codes you can handle meaningfully before falling through to a generic !response.ok check. Always guard response.json() on the error path - a 502 from a proxy might return HTML instead of JSON.
Best Practices Summary
- Use consistent property naming.
camelCaseis standard in JavaScript APIs,snake_caseis common in Python and Ruby APIs. Pick one convention and stick with it across every endpoint; our guide to JSON key naming conventions covers the tradeoffs. - Return dates as ISO 8601 strings (
2026-03-05T08:30:00Z). Never use Unix timestamps unless your documentation makes it extremely clear. See JSON date formats for the details. - Use
nullfor absent values, not empty strings or the number zero. There is a semantic difference between "no value" and "blank value." Decide up front whether a missing key and an explicitnullmean the same thing in your API; JSON null vs undefined explains why that distinction matters. - Include a
requestIdin error responses so support teams can trace issues through logs and correlate client reports with server-side events. - Do not return more data than the client needs. Over-fetching wastes bandwidth and increases the risk of leaking sensitive fields.
- Validate and pretty-print your API responses during development to catch structural problems early.
For a deeper look at how JSON compares to the XML format it replaced, read our JSON vs XML comparison. And when your API responses need to be as compact as possible, our guide on how to minify JSON covers techniques for reducing payload size without sacrificing readability during development.
When an endpoint explicitly accepts a JSON filter in its query string, use the JSON URL query tests for special characters, repeated parameters and validation before execution.