Common JSON Structures You'll Encounter in REST APIs

If you work with REST APIs, you will encounter certain JSON patterns over and over. Recognising these common structures saves significant time when integrating new APIs - you can immediately understand the shape of a response rather than reading through documentation from scratch.

1. The Wrapped Response

Most production APIs do not return raw data at the root level. Instead, they wrap it in an envelope object that includes metadata about the response:

{
  "data": {
    "id": 42,
    "name": "Alice",
    "email": "alice@example.com"
  },
  "status": "success",
  "message": "User retrieved successfully"
}

The actual resource lives inside data, while status and message provide metadata. This pattern makes error handling consistent - you always check status before accessing data.

2. Paginated List Responses

When an endpoint can return many items, it paginates them to keep responses fast:

{
  "data": [
    { "id": 1, "name": "Item One" },
    { "id": 2, "name": "Item Two" }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 245,
    "total_pages": 25,
    "next": "/api/items?page=2",
    "previous": null
  }
}

Some APIs use cursor-based pagination instead of page numbers - next_cursor and prev_cursor fields point to the adjacent pages using opaque tokens rather than page indices.

3. Error Responses

A consistent error structure is a hallmark of a well-designed API:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields failed validation",
    "details": [
      { "field": "email", "issue": "required" },
      { "field": "name", "issue": "too_short", "min": 2 }
    ]
  }
}

The code field is a machine-readable constant your code can switch on, while message is human-readable. The details array allows multiple validation errors to be reported at once.

4. Nested Resource Responses

APIs often embed related resources in a single response to reduce the number of round trips:

{
  "order": {
    "id": "ord_001",
    "status": "shipped",
    "customer": {
      "id": 99,
      "name": "Bob",
      "email": "bob@example.com"
    },
    "items": [
      {
        "product_id": 12,
        "name": "Wireless Headphones",
        "quantity": 2,
        "unit_price": 49.99
      }
    ],
    "total": 99.98,
    "currency": "USD"
  }
}

5. JSON Array at Root

Some endpoints - particularly older or simpler ones - return a plain array at the root level rather than a wrapper object:

[
  { "id": 1, "name": "Tag A", "slug": "tag-a" },
  { "id": 2, "name": "Tag B", "slug": "tag-b" }
]

This is simpler but less flexible - there is no room to add pagination or status metadata without a breaking change to the API.

6. Hypermedia / HATEOAS

More advanced REST APIs include links to related actions directly in the response:

{
  "order": { "id": "ord_001", "status": "pending" },
  "links": {
    "self": "/api/orders/ord_001",
    "cancel": "/api/orders/ord_001/cancel",
    "customer": "/api/customers/99"
  }
}

Mapping API Responses Quickly

When you first integrate a new API, the fastest way to understand its response structure is to extract all the keys at once. Paste the API response into JSON Keyper and you will get a flat list of every key path in seconds - no more manually scrolling through hundreds of lines of JSON to find the field you need.