JSON API Response Example: Real-World Patterns

How APIs Use JSON

Nearly every modern REST API returns JSON. The format is lightweight, human-readable, and natively understood by JavaScript. While there's no single official standard for how API responses should be structured, a few patterns have emerged as best practice. This guide covers the three you'll encounter most often.

Pattern 1: Success Response With Data

When an API call succeeds, the response typically wraps the requested data in a predictable envelope:

{
  "status": "success",
  "data": {
    "user": {
      "id": 1042,
      "name": "Sarah Mitchell",
      "email": "sarah@example.com",
      "avatar": "https://cdn.example.com/avatars/1042.jpg",
      "role": "admin",
      "createdAt": "2024-03-15T08:00:00Z",
      "lastLogin": "2025-01-20T14:22:00Z"
    }
  },
  "meta": {
    "requestId": "req_abc123def456",
    "responseTime": "45ms"
  }
}

Key conventions in this pattern:

• Consistent envelope. The status field tells consumers whether the request succeeded without checking HTTP status codes.
• Data wrapper. The actual payload lives inside data, which keeps the top level clean for metadata.
• Meta information. Request IDs and timing data help with debugging and monitoring.

Pattern 2: Error Response

When something goes wrong, the response should clearly communicate what happened and how to fix it:

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields.",
    "details": [
      {
        "field": "email",
        "issue": "Invalid email format",
        "value": "not-an-email"
      },
      {
        "field": "age",
        "issue": "Must be a positive integer",
        "value": -5
      }
    ]
  },
  "meta": {
    "requestId": "req_xyz789ghi012",
    "documentation": "https://api.example.com/docs/errors#VALIDATION_ERROR"
  }
}

Good error responses share several traits:

• Machine-readable error code. VALIDATION_ERROR is easier to handle programmatically than a free-text message.
• Human-readable message. A clear description of what went wrong.
• Field-level details. For validation errors, listing each problematic field with the specific issue helps developers fix their requests quickly.
• Documentation link. Pointing to relevant docs reduces support load.

Pattern 3: Paginated List Response

When returning a collection of items, APIs almost always paginate to avoid sending thousands of records at once:

{
  "status": "success",
  "data": [
    {
      "id": 301,
      "title": "Introduction to JSON",
      "author": "Alice Chen",
      "publishedAt": "2025-01-10T09:00:00Z",
      "tags": ["json", "tutorial", "beginner"]
    },
    {
      "id": 302,
      "title": "Advanced API Design",
      "author": "Bob Martinez",
      "publishedAt": "2025-01-12T11:30:00Z",
      "tags": ["api", "rest", "advanced"]
    },
    {
      "id": 303,
      "title": "JSON Schema Validation",
      "author": "Carol Johnson",
      "publishedAt": "2025-01-15T14:00:00Z",
      "tags": ["json", "schema", "validation"]
    }
  ],
  "pagination": {
    "currentPage": 2,
    "perPage": 3,
    "totalPages": 17,
    "totalItems": 50,
    "hasNextPage": true,
    "hasPreviousPage": true,
    "links": {
      "first": "/api/articles?page=1&per_page=3",
      "previous": "/api/articles?page=1&per_page=3",
      "next": "/api/articles?page=3&per_page=3",
      "last": "/api/articles?page=17&per_page=3"
    }
  }
}

The pagination object gives consumers everything they need to navigate the full dataset:

• Page metadata — current page, items per page, and totals let the frontend build pagination controls.
• Boolean flags — hasNextPage and hasPreviousPage simplify conditional rendering of navigation buttons.
• Prebuilt links — providing full URLs for first, previous, next, and last pages follows the HATEOAS principle and reduces client-side URL construction.

Response Envelope Conventions

Different APIs follow different conventions. Here are the most common approaches:

• Envelope pattern (shown above) — wraps all responses in { status, data, meta }. Popular with custom APIs.
• Direct data — returns the data object or array directly without a wrapper. Simpler but makes error handling less consistent.
• JSON:API spec — a formal specification with strict rules for resource objects, relationships, and included data.

Pick one convention and stick with it across your entire API. Consistency is more important than which pattern you choose.

Common Mistakes to Avoid

• Inconsistent response shapes. If successful responses use data but errors return a flat message string, consumers need different parsing logic for every endpoint.
• Sending 200 OK for errors. Always use appropriate HTTP status codes (400, 401, 404, 500) alongside your JSON error body.
• Missing pagination on list endpoints. Returning all records works in development but causes timeouts and memory issues in production.
• Exposing internal details. Never include stack traces, database queries, or internal IDs in production error responses.
• Vague error messages."Something went wrong" doesn't help anyone. Be specific about what failed and what the consumer can do about it.