REST API Cheat Sheet

REST API URL Design Rules

Keep nesting shallow — avoid going deeper than two levels (e.g., /users/123/posts is fine, /users/123/posts/456/comments/789/likes is too deep).

Offset-Based Pagination

Simple and widely used. Allows jumping to any page. Can be slow on large datasets.

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

Response Headers:
  X-Total-Count: 150
  Link: </api/users?page=3&per_page=20>; rel="next",
        </api/users?page=1&per_page=20>; rel="prev",
        </api/users?page=8&per_page=20>; rel="last"

Response Body:
{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

Cursor-Based Pagination

Better performance on large datasets. No skipping pages. Consistent results even when data changes.

GET /api/users?cursor=abc123&limit=20

Response Body:
{
  "data": [...],
  "meta": {
    "next_cursor": "def456",
    "has_more": true
  }
}

Use offset pagination for small/medium datasets where users need page numbers. Use cursor pagination for large datasets, real-time feeds, or infinite scroll.

Standard Error Response

Always return a consistent error structure across your API:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields.",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address."
      },
      {
        "field": "age",
        "message": "Must be a positive integer."
      }
    ]
  }
}

How Content Negotiation Works

The client specifies what format it wants using the Accept header, and what format it is sending using the Content-Type header:

# Client requests JSON response and sends JSON body
POST /api/users HTTP/1.1
Accept: application/json
Content-Type: application/json

{"name": "Jane Doe"}

# Client requests XML response
GET /api/users/123 HTTP/1.1
Accept: application/xml

# Client sends form data
POST /api/login HTTP/1.1
Content-Type: application/x-www-form-urlencoded

username=jane&password=secret

Rate Limit Response Example

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1707667200
Retry-After: 30

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 30 seconds."
  }
}