Skip to content
APIs

JSON in REST APIs: Structure and Security

·8 min read
JSON in REST APIs: Structure and Security - APIs guide from JSON Prettifier

Quick answer: Send and return JSON with Content-Type: application/json, wrap collections in a data object 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-readable code, pick offset or cursor pagination based on dataset size, and version breaking changes in the URL path (/api/v2/). Keep naming, date formats, and null handling 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. camelCase is standard in JavaScript APIs, snake_case is 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 null for 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 explicit null mean the same thing in your API; JSON null vs undefined explains why that distinction matters.
  • Include a requestId in 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.

Frequently Asked Questions

What Content-Type header should a JSON REST API use?
Send and return application/json. Set Content-Type on requests that carry a JSON body, and send Accept: application/json so the server knows which format you want back. Proxies, middleware, and client libraries all rely on these headers to decide how to handle the body.
Should a JSON API return a bare array or wrap it in an object?
Wrap collections in an object with a data key. A top-level object leaves room for meta, pagination, or links without breaking existing clients, and it avoids the historical JSON hijacking problem that bare top-level arrays had.
How should errors be returned in a JSON API?
Use the correct HTTP status code (400, 401, 404, 422, 500) and put the details in a structured body with a machine-readable code, a human-readable message, and a details array for field-level problems. Never return a 200 with an error hidden inside the body.
Which pagination style is best for a JSON API?
Offset pagination (page and perPage) is simplest and lets clients jump to any page, but gets slow on large tables and can skip or duplicate rows. Cursor pagination is faster at scale and immune to row shifting, at the cost of random page access. GitHub-style Link headers keep the body clean but need header parsing.
What is the most common way to version a JSON REST API?
URL path versioning such as /api/v2/users is the most widely adopted because it is explicit, easy to route, and obvious in documentation. Header versioning and query-parameter versioning also work, but whichever you pick, give clients a migration window before removing old versions.

Debug API Responses Instantly

Debugging an API response? Paste the raw JSON into our formatter to instantly see the structure with syntax highlighting.

Open JSON Prettifier