JSON Formatting Best Practices for Clean API Responses

What Makes Good JSON?

JSON (JavaScript Object Notation) is inherently flexible. You can structure it however you want. However, this flexibility is a double-edged sword. If an API returns an array for one endpoint, an object for another, and a string for an error message on a third, it forces frontend developers to write complex, brittle parsing logic.

"Good JSON" is predictable, consistent, self-describing, and follows industry standards. When a developer consumes your API, they should be able to guess the shape of the response before even looking at the documentation.

Naming Conventions

The most debated topic in API design is casing. Should you use first_name, firstName, or FirstName?

• camelCase: The overwhelming industry standard for JSON. Since JSON originated from JavaScript, and JS uses camelCase, it allows for seamless object destructuring on the frontend.
• snake_case: Popular in Ruby and Python ecosystems. Some APIs use this, but it often requires transformation layers on the frontend.

Wrapping Data in Envelopes

It might be tempting to return an array directly at the root of a JSON response, like this: [{ "id": 1 }, { "id": 2 }]. However, this pattern removes your ability to add metadata later.

Always wrap your primary response in a data object. This pattern, popularized by standards like JSON:API, allows you to seamlessly introduce pagination, links, or performance metrics alongside the actual data.

Handling Nulls and Empty States

How you handle missing data significantly impacts frontend stability:

• Lists/Arrays: If a user has no posts, return an empty array [], never null. This prevents .map() is not a function errors in JavaScript.
• Strings: If a string is missing, return null or an empty string "". Do not omit the key entirely, as it makes the data model unpredictable.
• Booleans: Never return null for a boolean. Default to false.

Pagination Best Practices

When returning lists of resources, pagination is mandatory. Because you are using a data envelope, you can easily add a meta object for pagination details.

A standard pagination block should include the currentPage, totalPages, totalItems, and itemsPerPage. Modern APIs often use cursor-based pagination (using nextCursor) for highly dynamic data feeds like social timelines.

Standardized Error Formatting

Error responses must be as structured as successful responses. The industry standard is RFC 7807 (Problem Details for HTTP APIs).

Instead of returning a raw string like "Invalid email", return an object containing a machine-readable code, a human-readable message, and optionally, a details array for form validation errors.

Dates and Times in JSON

All dates and times in JSON should be formatted as ISO 8601 UTC strings (e.g., "2026-05-21T14:30:00Z") or as Unix epoch timestamps (integers). This ensures the frontend can parse the exact absolute time and format it according to the user's local browser settings.

Code Examples

{
  "data": [
    {
      "id": "usr_123abc",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "isActive": true,
      "roles": ["admin", "editor"],
      "lastLoginAt": "2026-05-21T10:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "currentPage": 1,
      "totalPages": 5,
      "totalItems": 42,
      "itemsPerPage": 10
    }
  }
}

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The provided payload contains invalid fields.",
    "details": [
      {
        "field": "email",
        "issue": "Must be a valid email address."
      },
      {
        "field": "password",
        "issue": "Must be at least 8 characters long."
      }
    ],
    "requestId": "req_882bVxz9"
  }
}

Frequently Asked Questions