JSON API Design Principles for Modern Applications

2026-01-30#JSON#API Design#REST#Best Practices

Well-designed JSON APIs are intuitive to use and easy to maintain. This guide covers principles and patterns for creating excellent APIs.

Response Envelope Patterns

Success Response

{
  "success": true,
  "data": {
    "id": 123,
    "name": "John Doe"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-01-30T10:00:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "must be a valid email address"
      }
    ],
    "requestId": "req_abc123"
  },
  "timestamp": "2026-01-30T10:00:00Z"
}

Pagination Patterns

Offset-Based

{
  "data": [...],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  }
}

Cursor-Based (Recommended for Large Datasets)

{
  "data": [...],
  "pagination": {
    "hasNext": true,
    "nextCursor": "cursor_abc123",
    "hasPrev": false
  }
}

Link: <https://api.example.com/users?page=2>; rel="next",
      <https://api.example.com/users?page=5>; rel="last"

Naming Conventions

Field Names

Use snake_case or camelCase consistently (pick one)
Avoid abbreviations (use userId not uid)
Use plural names for arrays: users, items

{
  "user_id": 123,
  "created_at": "2026-01-30T10:00:00Z",
  "email_addresses": [
    {"type": "work", "address": "user@example.com"}
  ]
}

API Endpoints

Pattern	Example
Collection	GET /users
Single Resource	GET /users/{id}
Related Resource	GET /users/{id}/posts
Action	POST /users/{id}/activate
Search	GET /users?search=john

Error Codes

Use consistent error codes:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data"
  }
}

Common error codes:

Code	Meaning
`VALIDATION_ERROR`	Request data failed validation
`NOT_FOUND`	Resource doesn't exist
`UNAUTHORIZED`	Authentication required
`FORBIDDEN`	Permission denied
`RATE_LIMITED`	Too many requests
`INTERNAL_ERROR`	Server error
`BAD_REQUEST`	Malformed request

Versioning

URL Versioning (Most Common)

/v1/users
/v2/users

Header Versioning

Accept: application/vnd.api+json;version=2

Content Negotiation

Support multiple formats:

Accept: application/json        // JSON (default)
Accept: application/vnd.api+json // JSON API
Accept: application/hal+json    // HAL

Sparse Fieldsets

Allow clients to request only needed fields:

GET /users?fields=id,name,email

Response:

{
  "data": [
    {"id": 1, "name": "John", "email": "john@example.com"}
  ]
}

Relationships and Embedding

Resource Links

{
  "id": 1,
  "name": "John",
  "_links": {
    "self": "/users/1",
    "posts": "/users/1/posts",
    "avatar": "/users/1/avatar"
  }
}

Embedded Resources

{
  "id": 1,
  "name": "John",
  "_embedded": {
    "posts": [
      {"id": 101, "title": "First Post"}
    ]
  }
}

Compound Documents

Include related resources in one request:

GET /users/1?include=posts,comments

Response includes both user and their posts/comments.

HATEOAS Links

Provide navigation links:

{
  "data": {...},
  "_links": {
    "self": "/orders/123",
    "cancel": "/orders/123/cancel",
    "ship": "/orders/123/ship",
    "next": "/orders/124",
    "profile": "/users/1"
  }
}

Rate Limiting Headers

Communicate rate limits:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Summary

Design JSON APIs with: consistent naming, clear error handling, pagination, proper versioning, and HATEOAS links. These patterns create APIs that are intuitive, maintainable, and evolve gracefully.