API Design Principles Cheat Sheet
REST conventions, HTTP status codes, versioning, pagination, and error-handling practices for designing consistent, well-behaved web APIs.
2 PagesIntermediateApr 15, 2026
REST Principles
Foundational constraints that make a web API predictable and cacheable.
- Resource-oriented URLs- Model nouns, not verbs: /orders/123/items instead of /getOrderItems?id=123
- Use HTTP methods correctly- GET reads, POST creates, PUT replaces, PATCH partially updates, DELETE removes
- Statelessness- Each request must carry all information needed to process it; the server holds no client session state
- Idempotency- GET, PUT, and DELETE should be safe to retry with the same result; POST generally is not idempotent
- Proper status codes- Communicate outcomes with standard HTTP status codes instead of always returning 200 with an error field
- HATEOAS- Responses can include links to related actions so clients navigate the API without hardcoding URLs
HTTP Methods & Status Codes
Quick reference for verb usage and the most common response codes.
http
GET /orders 200 OK # list resourcesGET /orders/123 200 OK | 404 Not FoundPOST /orders 201 Created # include a Location headerPUT /orders/123 200 OK | 204 No Content # full replacePATCH /orders/123 200 OK # partial updateDELETE /orders/123 204 No Content# Common status codes200 OK # success201 Created # resource created204 No Content # success, no response body400 Bad Request # malformed request or validation failure401 Unauthorized # missing or invalid credentials403 Forbidden # authenticated but not allowed404 Not Found409 Conflict # e.g. duplicate resource, version mismatch422 Unprocessable Entity # semantically invalid payload429 Too Many Requests # rate limited500 Internal Server Error
Versioning & Pagination
Common approaches to API versioning and paging through collections.
javascript
// URL versioning (easy to route and cache)// GET https://api.example.com/v1/orders// Header versioning (keeps URLs clean)// GET /orders// Accept: application/vnd.example.v1+json// Cursor-based pagination response{ "data": [ { "id": 101, "total": 42.5 }, { "id": 102, "total": 17.0 } ], "pagination": { "next_cursor": "eyJpZCI6MTAyfQ==", "has_more": true, "limit": 20 }}// Offset-based pagination request// GET /orders?limit=20&offset=40
API Design Best Practices
Habits that keep an API stable and pleasant for client developers.
- Version your API- Use /v1/, /v2/ in the URL or an Accept header so breaking changes don't break existing clients
- Consistent naming- Use plural nouns for collections (/users) and one casing convention for fields across the whole API
- Filter, sort, and paginate- /orders?status=paid&sort=-created_at&limit=20 instead of returning an entire dataset
- Meaningful error bodies- {"error":{"code":"INVALID_EMAIL","message":"..."}} instead of a bare 400 with no detail
- Idempotency keys for POST- Accept an Idempotency-Key header so retried creates don't double-charge or duplicate
- Document with OpenAPI- Provide a machine-readable spec so clients can generate SDKs and see the contract
- Communicate rate limits- Return X-RateLimit-Limit/Remaining/Reset headers so clients can back off gracefully
- Never break existing fields- Add new optional fields instead of renaming or removing existing ones within the same version
Stable Cursor Pagination Under Concurrent Writes
Offset pagination silently skips or repeats rows when the underlying set changes; a cursor keyed on a stable, indexed column avoids that.
javascript
// BAD: offset drifts when rows are inserted/deleted between pages// GET /orders?limit=20&offset=40 -> page 3 can repeat or skip rows// GOOD: opaque cursor encodes the last seen (created_at, id) tuplefunction encodeCursor(order) { return Buffer.from(JSON.stringify({ ts: order.created_at, id: order.id })).toString('base64url');}function decodeCursor(cursor) { return JSON.parse(Buffer.from(cursor, 'base64url').toString());}// SQL: seek past the cursor using a compound comparison, not OFFSET// SELECT * FROM orders// WHERE (created_at, id) < (:cursor_ts, :cursor_id)// ORDER BY created_at DESC, id DESC// LIMIT 20app.get('/orders', (req, res) => { const after = req.query.cursor ? decodeCursor(req.query.cursor) : null; const rows = fetchOrdersAfter(after, 20); const nextCursor = rows.length === 20 ? encodeCursor(rows[rows.length - 1]) : null; res.json({ data: rows, pagination: { next_cursor: nextCursor, has_more: !!nextCursor } });});
Conditional Requests: ETag & Optimistic Concurrency
ETags double as cache validators and as a safe way to prevent lost updates on concurrent PUT/PATCH.
http
# 1. Client fetches a resource, server returns a fingerprintGET /documents/42200 OKETag: "a1b2c3d4"# 2. Client re-fetches later; server can skip the body if unchangedGET /documents/42If-None-Match: "a1b2c3d4"304 Not Modified # no body sent, saves bandwidth# 3. Client wants to update, but only if no one else changed it sincePUT /documents/42If-Match: "a1b2c3d4"Content-Type: application/json{ "title": "New title" }# If another writer already changed the resource, the ETag no longer# matches and the server rejects the write instead of silently# overwriting the other writer's change412 Precondition Failed
RFC 9457 Problem Details for Errors
A standardized, machine-parseable error body instead of an ad-hoc {error: string} shape.
json
// Response for a validation failure — note the standard fields plus// API-specific extensions under the same flat objectHTTP/1.1 422 Unprocessable EntityContent-Type: application/problem+json{ "type": "https://api.example.com/errors/validation-failed", "title": "One or more fields are invalid", "status": 422, "detail": "email must be a valid address", "instance": "/orders/123", "errors": [ { "field": "email", "code": "INVALID_FORMAT" }, { "field": "quantity", "code": "MUST_BE_POSITIVE" } ]}// 'type' is a dereferenceable URI clients can match on programmatically// instead of parsing free-text 'title'/'detail' strings
Beyond REST: When gRPC or GraphQL Fit Better
REST is not the only option — pick the transport based on the client fan-out and latency shape, not habit.
protobuf
// gRPC: strongly-typed contract, binary protobuf, HTTP/2 streaming —// good fit for internal service-to-service calls needing low latencyservice OrderService { rpc GetOrder (GetOrderRequest) returns (Order); rpc StreamOrderUpdates (OrderId) returns (stream OrderEvent); // server streaming}message Order { string id = 1; double total = 2; repeated string item_ids = 3;}// GraphQL: single endpoint, client specifies exact shape — good fit// for aggregating many resources per screen without over/under-fetching// query {// order(id: "123") { id total items { name price } }// }// but: caching is harder (no per-resource URL), and a single expensive// nested query can fan out into N+1 backend calls without dataloaders
API Design Gotchas That Surface Late
Decisions that look fine in a first release but become expensive to change once clients depend on them.
- PATCH semantics ambiguity- JSON Merge Patch (RFC 7396) can't express 'delete a field' unambiguously from 'set to null'; JSON Patch (RFC 6902) is more precise but harder for clients to construct
- Idempotency key scope- An Idempotency-Key must be scoped per-endpoint (or per-endpoint+body-hash), not globally, or two different unrelated requests reusing a key will collide
- Breaking change via 'additive' field- Adding a required field to a request body is a breaking change even though it 'just adds a field' — existing clients omit it and start failing validation
- Deep pagination cost- OFFSET-based pagination degrades linearly with offset size on most databases; deep pages (offset=100000) can be orders of magnitude slower than page 1
- Timestamp format drift- Mixing epoch millis and ISO 8601 strings across endpoints forces every client to special-case parsing; standardize on RFC 3339 UTC with explicit 'Z'
- Sunsetting old versions silently- Removing a deprecated API version without a Sunset/Deprecation header and a migration window breaks integrators with no warning
- Bulk endpoints and partial failure- A batch POST that partially succeeds needs a per-item status array in the response body, not a single top-level status code that hides which items failed
Pro Tip
Design your API's error response schema with the same rigor as your success responses from day one — retrofitting a consistent error shape after clients are already parsing ad-hoc error fields is far more painful than starting with one.
Was this cheat sheet helpful?
Explore Topics
#APIDesignPrinciples#APIDesignPrinciplesCheatSheet#Programming#Intermediate#RESTPrinciples#HTTP#Methods#Status#Networking#WebDevelopment#APIs#CheatSheet#SkillVeris
