JSON REST API Best Practices

Response Envelope Structure

Consistent response shapes reduce client-side surprises. Pick a pattern and stick to it:

// Success
{
  "data": { "id": 1, "name": "Alice" },
  "meta": { "requestId": "abc123" }
}

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required"
  }
}

Naming Conventions

HTTP Status Codes

Pagination

// Cursor-based (recommended for large datasets)
{
  "data": [...],
  "meta": { "nextCursor": "abc", "hasMore": true }
}

// Offset-based
{
  "data": [...],
  "meta": { "total": 1250, "page": 3, "perPage": 20 }
}

FAQ