Working with JSON in APIs

JSON in API requests

An HTTP request has more than a body: it also has a method, URL, headers, and a status from the server. When an endpoint accepts a JSON body, clients commonly send a Content-Type: application/json header and serialize one JSON value as the body. The API documentation—not JSON itself—defines which keys are accepted and what they mean.

{
  "name": "Ari Chen",
  "email": "[email protected]",
  "preferences": {
    "newsletter": false
  }
}

This is only the body data. It does not include an authentication token, URL, HTTP method, or headers. Do not put secrets into sample data or share credentials when testing APIs.

Reading a success response

HTTP status codes communicate request outcomes, while the response body contains the API's chosen data structure. Many APIs put returned records under a data property and add metadata separately. This is a convention, not a universal JSON requirement.

{
  "success": true,
  "status": 200,
  "data": [
    {
      "id": "item-101",
      "name": "Notebook",
      "price": 4.5,
      "available": true
    }
  ],
  "meta": {
    "requestId": "sample-request-01",
    "servedAt": "2026-01-15T09:30:00Z"
  }
}

Check the API contract to learn whether a successful result is an object, an array, or wrapped in an envelope. Do not assume that every endpoint uses the same shape.

Reading an error response

When a request fails, an API may return a non-success HTTP status and a JSON body explaining the issue. The body shape varies by API. A client should handle both transport-level failure and the documented error payload; it should not assume an error response contains a success-style data array.

{
  "success": false,
  "status": 400,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "One or more fields need attention.",
    "fields": [
      {
        "name": "email",
        "issue": "Use a valid email address."
      }
    ]
  },
  "requestId": "sample-request-02",
  "retryable": false
}

The sample is fictional and illustrates one possible design. In a real application, use the endpoint's documentation and avoid showing internal diagnostic details directly to end users.

Nested response data

API responses often contain arrays of records, each with nested objects or arrays. Use a viewer or tree view to explore the structure before writing code that accesses it. Check whether a field may be absent, null, or an empty collection; these cases are not interchangeable.

Pagination and metadata

Large result sets are often split into pages. The response may include the current page, page size, total count, and flags or links for navigating. The exact shape depends on the API. If you need every record, your client may have to request multiple pages and follow the API's documented next-page mechanism.

{
  "data": [
    { "id": 21, "name": "Mira" },
    { "id": 22, "name": "Theo" }
  ],
  "pagination": {
    "page": 2,
    "pageSize": 2,
    "totalItems": 7,
    "totalPages": 4,
    "hasPreviousPage": true,
    "hasNextPage": true,
    "nextPage": 3,
    "previousPage": 1
  }
}

How to inspect an API response

1. Use the API's documentation to identify the endpoint, expected status codes, and response shape.
2. Capture a response using an authorized client or development environment. Remove credentials and personal data before sharing it.
3. Paste the response into the JSON Validator to check JSON syntax.
4. Use the JSON Formatter to read indentation or the JSON Viewer to explore nested values.
5. Compare the actual values with the API contract. A syntactically valid response can still violate an expected schema or business rule.

Practice with the fictional API success, API error, and pagination datasets. They are local examples, not live endpoint responses.

Key takeaways

• HTTP defines request and response mechanics; JSON represents structured body data.
• Response envelopes and pagination shapes are API-specific conventions.
• Validate syntax, then check the response against the API contract.
• Handle error responses, missing fields, nulls, and empty arrays deliberately.