Technical reference

REST APIs Cheatsheet

Design and consume predictable HTTP APIs

Must Know

Use nouns for resources and methods for intent.

GET /users/42
POST /users
PATCH /users/42
DELETE /users/42

200 OK
201 Created
204 No Content
400 Bad Request
401 Unauthenticated
403 Forbidden
404 Not Found
409 Conflict
422 Validation Error
500 Server Error

json

Keep success and error shapes stable.

{
  "data": { "id": "42", "name": "Luis" },
  "meta": { "requestId": "req_123" }
}

json

Return machine-readable codes and human-readable messages.

{
  "error": { "code": "VALIDATION_ERROR", "message": "Invalid input", "fields": { "email": "Required" } }
}

Cap page size and use stable ordering.

GET /users?limit=20&cursor=eyJpZCI6NDJ9

{ "data": [], "nextCursor": "..." }

ETags reduce bandwidth and can prevent lost updates.

ETag: "user-42-v7"
If-None-Match: "user-42-v7"

304 Not Modified

Essential for retrying non-idempotent operations safely.

POST /payments
Idempotency-Key: 9d62...

// Same key + same request => same result

Design observability and limits with the endpoint.

request IDs
structured logs
timeouts
rate limits
API versioning
OpenAPI documentation