JSON formatting best practices for API responses Written on Apr 7, 2026. Posted in Tutorials.

Consistent naming saves hours of integration debugging

Pick one convention and stick to it across your entire API. The three options:

• snake_case: user_id, created_at — standard in Python/Rails/Laravel
• camelCase: userId, createdAt — standard in JavaScript/Node
• kebab-case: user-id — avoid this in JSON keys, it requires quoting

The worst thing you can do is mix them. user_id in one endpoint and userId in another breaks client SDKs and generates confusion.

Always return a consistent envelope

// Success
{
  "data": { ... },
  "meta": { "request_id": "abc123", "took_ms": 42 }
}

// Error
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The email field is required.",
    "details": [
      { "field": "email", "issue": "required" }
    ]
  }
}

Never return raw data at the root level for collection endpoints — it makes pagination impossible to add later without a breaking change.

Pagination shape that works with every client

{
  "data": [...],
  "pagination": {
    "total": 1042,
    "per_page": 20,
    "current_page": 3,
    "last_page": 53,
    "next_cursor": "eyJpZCI6NjB9"
  }
}

Include both offset pagination fields AND a cursor for high-volume endpoints. The cursor lets clients resume without re-querying the count.

Dates: always ISO 8601 UTC

"created_at": "2026-04-07T14:32:00Z" — always include timezone (Z or +00:00). Never return Unix timestamps without also providing the ISO string. Never return locale-formatted date strings like "April 7, 2026".

Debug and pretty-print any JSON instantly

Paste minified or malformed JSON to see a collapsible tree, validate syntax, and copy formatted output.

Open JSON Formatter →