REST API JSON Design Best Practices 2026: 8 Rules Every Developer Must Follow

// ── Success ───────────────────────────────────────────────────────────────
200 OK           — GET, PUT, PATCH succeeded with a response body
201 Created      — POST created a new resource (include Location header)
204 No Content   — DELETE succeeded, or PUT/PATCH with no response body needed

// ── Client errors (the client did something wrong) ─────────────────────────
400 Bad Request  — invalid JSON body, missing required field, malformed input
401 Unauthorized — no auth token, or token is invalid / expired
403 Forbidden    — token is valid but user lacks permission for this resource
404 Not Found    — resource does not exist (or you are hiding it from unauthorized users)
409 Conflict     — duplicate resource (email already exists, version conflict)
422 Unprocessable — valid JSON, but business logic validation failed (age must be > 0)
429 Too Many Requests — rate limit exceeded (include Retry-After header)

// ── Server errors (your code failed) ──────────────────────────────────────
500 Internal Server Error — unexpected server-side failure
503 Service Unavailable   — downstream dependency is down, try again later

// ── Validation error (422) ────────────────────────────────────────────────
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid values.",
    "details": [
      { "field": "email",    "code": "INVALID_FORMAT",  "message": "Must be a valid email address" },
      { "field": "age",      "code": "OUT_OF_RANGE",    "message": "Must be between 0 and 150" },
      { "field": "username", "code": "ALREADY_EXISTS",  "message": "This username is already taken" }
    ]
  },
  "requestId": "req_xyz789"
}

// ── Auth error (401) ──────────────────────────────────────────────────────
{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Your access token has expired. Use the refresh token to obtain a new one."
  },
  "requestId": "req_abc456"
}

// ── Rate limit error (429) ────────────────────────────────────────────────
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please wait 60 seconds before retrying."
  },
  "requestId": "req_def123"
}
// Also set: Retry-After: 60  (header)

// Request: GET /api/v1/users?limit=20&cursor=cursor_abc123
// Response:
{
  "data": [
    { "id": "usr_101", "name": "Alice Chen" },
    { "id": "usr_102", "name": "Bob Kim" }
  ],
  "meta": {
    "total":       1284,         // total matching records
    "count":       20,           // records in this page
    "limit":       20,           // requested page size
    "nextCursor":  "cursor_xyz456",  // null when this is the last page
    "prevCursor":  "cursor_abc123",  // null on first page
    "hasNextPage": true
  }
}

// Why cursor over offset?
// Offset: SELECT * FROM users LIMIT 20 OFFSET 10000  — full table scan, slow
// Cursor: SELECT * FROM users WHERE id > last_id LIMIT 20  — index seek, instant
// Offset also has the "shifting window" bug: new inserts while paginating cause skips

// ✅ Version in URL path — recommended
GET /api/v1/users
GET /api/v2/users       // v2 with breaking changes — v1 still works
GET /api/v1/users/123   // consistent structure

// ⚠️ Version in header — valid but less visible, harder to test in browser
GET /api/users
Accept: application/vnd.myapp.v1+json

// ⚠️ Version in query param — works but pollutes query string
GET /api/users?version=1

// Breaking vs non-breaking changes:
// NON-BREAKING (safe to add without bumping version):
//   + Adding new optional fields to responses
//   + Adding new optional query parameters
//   + Adding new endpoints
//   + Relaxing validation rules

// BREAKING (always bump the version):
//   - Removing or renaming fields
//   - Changing field types (string → number)
//   - Changing error codes
//   - Making optional fields required
//   - Changing pagination format