Tags: rest, api, http, status-codes, idempotency, pagination, headers, backend Last updated: 2026-06-26

RESTful API Design Cheatsheet

Quick Reference

Concept	Key Point
GET	Safe, idempotent, cacheable
POST	Not idempotent, creates resource
PUT	Idempotent, full replacement
PATCH	Not necessarily idempotent
DELETE	Idempotent, removes resource
200 OK	Success
201 Created	Resource created
400 Bad Request	Client error
401 Unauthorized	Missing/invalid auth
403 Forbidden	Insufficient permissions
404 Not Found	Resource doesn't exist
422 Unprocessable	Validation failure
429 Too Many Requests	Rate limited
500 Internal Server Error	Server error

HTTP Methods & Semantics

Method	Idempotent	Safe	Body	Use For
`GET`	Yes	Yes	No	Retrieve resource(s)
`POST`	No	No	Yes	Create a new resource
`PUT`	Yes	No	Yes	Full replace or upsert
`PATCH`	Maybe	No	Yes	Partial update
`DELETE`	Yes	No	No	Remove a resource

Status Codes

2xx — Success

200 OK — Standard success response.
201 Created — Resource created; include Location header.
204 No Content — Success with no body (common for DELETE).

4xx — Client Errors

400 Bad Request — Malformed syntax.
401 Unauthorized — Missing or invalid authentication.
403 Forbidden — Authenticated but not allowed.
404 Not Found — Resource doesn't exist.
409 Conflict — Resource state conflict.
422 Unprocessable Entity — Validation error.
429 Too Many Requests — Rate limited; include Retry-After.

Resource Naming

GET    /users              # List users
POST   /users              # Create a user
GET    /users/42           # Get user 42
PUT    /users/42           # Replace user 42
PATCH  /users/42           # Partial update
DELETE /users/42           # Delete user 42

# Sub-resources
GET    /users/42/orders    # User 42's orders

Pagination

Cursor-Based

GET /users?cursor=eyJpZCI6NDJ9&limit=20
{ "data": [...], "pagination": { "next": "...", "has_more": true } }

Offset-Based

GET /users?offset=40&limit=20
{ "data": [...], "pagination": { "offset": 40, "limit": 20, "total": 157 } }

Filtering & Sorting

GET /users?status=active&role=admin       # Filter
GET /users?q=john                         # Search
GET /users?sort=-created_at,+name          # Sort
GET /users?fields=id,name,email           # Sparse fieldsets

Headers

# Request
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: unique-key-123
If-Match: "etag-value"

# Response
Location: /users/42
Retry-After: 120
X-Request-Id: abc-123

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "field": "email", "message": "Must be valid" }
    ],
    "request_id": "req_abc123"
  }
}

Tips

Always use TLS — never send auth tokens over plain HTTP.
Include a request_id in every response for debugging.
Prefer cursor-based pagination for any dataset that can grow.
Never expose stack traces in 5xx responses in production.