JSON Best Practices for REST APIs

Table of Contents

• Naming Conventions
• Response Envelope
• Error Format
• Pagination
• Dates and Times

Naming Conventions

Stick to camelCase for JSON keys in JavaScript-facing APIs, or snake_case if you follow the Google JSON Style Guide. The key rule: be consistent.

{
  "userId": 1,
  "firstName": "Trong",
  "createdAt": "2025-01-15T10:00:00Z"
}

Response Envelope

Wrap responses in a consistent envelope so clients know what to expect:

{
  "success": true,
  "data": { "id": 1, "name": "HeoLab" },
  "meta": { "requestId": "abc-123" }
}

Error Format

Never return raw error strings. Use a structured format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "field": "email"
  }
}

Pagination

Use cursor-based pagination for large datasets:

{
  "data": ["..."],
  "pagination": {
    "total": 1000,
    "page": 1,
    "perPage": 20,
    "nextCursor": "eyJpZCI6MjB9"
  }
}

Dates and Times

Always use ISO 8601 format in UTC. Never return raw Unix timestamps as the primary date format.

{
  "publishedAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-01T08:00:00Z"
}