JSON Best Practices for REST APIs in 2026

Bad JSON in an API response causes real problems — confused clients, hard-to-debug errors, and brittle integrations. After reviewing hundreds of public APIs, here are the 10 rules that separate good JSON API design from great JSON API design.

1. Use camelCase for property names

// ✗ Avoid
{ "first_name": "Alice", "last_name": "Smith" }

// ✓ Prefer
{ "firstName": "Alice", "lastName": "Smith" }

camelCase is the JavaScript convention and matches how most client developers will store it in their variables. If you use snake_case (common in Python/Ruby APIs), be consistent — never mix them.

2. Always return objects, not arrays

// ✗ Fragile — hard to extend
["Alice", "Bob", "Carol"]

// ✓ Extensible
{
  "users": ["Alice", "Bob", "Carol"],
  "total": 3
}

Wrapping arrays in objects gives you room to add metadata (pagination, counts, status) without breaking existing clients.

3. Use consistent date formats — ISO 8601

// ✗ Ambiguous and regional
{ "created": "11/14/23" }

// ✓ Unambiguous, timezone-aware
{ "created": "2023-11-14T22:13:20Z" }

ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) is the international standard. It's sortable, parseable by every language, and unambiguous about timezone (Z = UTC).

4. Use null, not empty strings or missing keys

// ✗ Inconsistent — client can't tell if value exists
{ "name": "Alice", "email": "" }
{ "name": "Bob" } // email missing entirely

// ✓ Consistent — null means "no value"
{ "name": "Alice", "email": null }
{ "name": "Bob",   "email": null }

5. Return meaningful error objects

// ✗ Useless
{ "error": true }

// ✓ Actionable
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Email address is invalid",
    "field": "email",
    "docs": "https://api.example.com/errors#validation"
  }
}

6. Use plural nouns for collections

// ✗
{ "user": [...] }

// ✓
{ "users": [...] }

7. Include pagination metadata

{
  "users": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

8. Never return different types for the same field

// ✗ Breaks client type systems
{ "id": 123 }     // sometimes number
{ "id": "abc" }   // sometimes string

// ✓ Always the same type
{ "id": "user_123" }  // always string

Use strings for IDs — they're future-proof. A numeric ID that exceeds Number.MAX_SAFE_INTEGER in JavaScript (9 quadrillion) silently loses precision.

9. Use HTTP status codes correctly

• 200 OK — success
• 201 Created — resource created
• 400 Bad Request — client sent invalid data
• 401 Unauthorized — not authenticated
• 403 Forbidden — authenticated but not authorized
• 404 Not Found — resource doesn't exist
• 422 Unprocessable Entity — validation failed
• 429 Too Many Requests — rate limited
• 500 Internal Server Error — server bug

10. Version your API in the URL

// ✓ Clear versioning
GET /api/v1/users
GET /api/v2/users

This lets you make breaking changes in v2 without breaking existing clients on v1.