JSON in REST APIs: Best Practices for API Design

JSON is the de facto standard for REST API payloads, but not all JSON APIs are created equal. Designing a JSON API that is consistent, predictable, and easy to consume requires following established conventions and avoiding common pitfalls. This guide covers REST API JSON best practices including naming conventions, response envelopes, error formats, pagination, versioning, and hypermedia. Use our JSON Formatter to visualize your API responses and JSON to OpenAPI to generate API specifications.

1. Naming Conventions

Style	Example	Recommendation
camelCase	firstName, createdAt	Recommended for JavaScript/TypeScript APIs
snake_case	first_name, created_at	Common in Python/Ruby APIs
PascalCase	FirstName, CreatedAt	Avoid — conflicts with class naming
kebab-case	first-name	Never — hyphens conflict with subtraction

The key rule: pick one convention and apply it consistently across all keys in all endpoints. Mixing conventions is the #1 API usability complaint.

2. Consistent Response Envelope

// Consistent success response
GET /api/users/123
{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Alice",
    "email": "alice@example.com"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

// Consistent error response
GET /api/users/999
{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "User with ID 999 not found",
    "details": null
  },
  "meta": {
    "requestId": "req_def456",
    "timestamp": "2025-01-15T10:30:01Z"
  }
}

3. Standard Error Format

Adopt RFC 7807 (Problem Details for HTTP APIs):

{
  "type": "https://api.example.com/errors/rate-limit",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 100 requests per minute.",
  "instance": "/api/users",
  "retryAfter": 60
}

4. Pagination with Pure Envelope

GET /api/users?page=2&per_page=20

{
  "data": [...],
  "pagination": {
    "page": 2,
    "perPage": 20,
    "total": 156,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": true,
    "nextPage": "/api/users?page=3&per_page=20",
    "prevPage": "/api/users?page=1&per_page=20"
  }
}

5. API Versioning

Three common approaches with JSON APIs:

Strategy	Example	Pros	Cons
URL Path	/api/v1/users	Most explicit, easy to route	Clutters URLs
Header	Accept: application/vnd.api+json;version=2	Clean URLs	Harder to debug, curl requires headers
Query param	/api/users?version=2	Easy to test	Cache pollution

6. Sparse Fieldsets and Partial Responses

Allow clients to request only the fields they need:

// Request: GET /api/users/123?fields=id,name,email
// Response:
{
  "data": {
    "id": 123,
    "name": "Alice",
    "email": "alice@example.com"
  }
  // 'age', 'address', 'phone' omitted
}

7. Hypermedia (HATEOAS)

{
  "data": {
    "id": 123,
    "name": "Alice",
    "_links": {
      "self": { "href": "/api/users/123" },
      "orders": { "href": "/api/users/123/orders" },
      "profile": { "href": "/api/users/123/profile" }
    }
  }
}

8. JSON:API Specification

The JSON:API specification standardizes REST API JSON formats with conventions for document structure, resource relationships, sparse fieldsets, pagination, and error responses. It includes built-in support for compound documents (including related resources), resource linkage, and extension points.

9. Security Headers for JSON Endpoints

Content-Type: application/json
X-Content-Type-Options: nosniff
Cache-Control: no-store
Strict-Transport-Security: max-age=31536000

10. Performance Best Practices

• Use our JSON Minifier to reduce response sizes in production
• Enable Gzip compression on your JSON endpoints (70-90% size reduction)
• Implement ETag and If-None-Match for conditional requests
• For large collections, implement cursor-based pagination instead of offset
• Use HTTP caching headers (Cache-Control, Expires) for stable resources
• Always validate JSON input with JSON Validator

Next Steps

Design your API with our JSON to OpenAPI tool. Test responses with JSON Formatter. Validate payloads with JSON Validator. Generate documentation from OpenAPI specs.