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

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?

Creational Design Patterns Cheat Sheet

Scikit-learn Cheat Sheet

Explore Topics

#APIDesignPrinciples#APIDesignPrinciplesCheatSheet#Programming#Intermediate#RESTPrinciples#HTTP#Methods#Status#Networking#WebDevelopment#APIs#CheatSheet#SkillVeris

Sri Hayavadhana Info-Tech

Professional Web Designing Services