🔌REST API Design Principles
Design REST APIs that teams can actually use — resources, verbs, versioning, and pagination, grounded in the conventions senior engineers argue about on PR threads.
Phase 1The Uniform Interface
Decode resources, verbs, and the uniform interface
URLs name things, not actions
6 minREST models your system as a set of nouns — resources — and the HTTP verbs do the verbs.
Each verb has a contract you inherit
6 minHTTP methods carry semantic guarantees — safety and idempotency — that clients and infrastructure rely on.
Status codes are your error language
7 minHTTP status codes are a shared vocabulary — clients, monitors, and caches all speak it, so use it precisely.
Phase 2Designing Endpoints For A Real Domain
Design endpoints for a small domain end-to-end
Plural nouns, nested paths, flat filters
7 minCollections are plural, individual resources nest under them, and filters live in query strings — not in the path.
Shape bodies around resources, not operations
6 minRequest and response bodies should look like the resource itself — so that GET and PUT can round-trip the same shape.
Errors are resources too
6 minA well-designed error response is structured data a client can act on — not a string.
Phase 3REST In Context: RPC, GraphQL, And Tradeoffs
Weigh REST against RPC and GraphQL tradeoffs
Your teammate proposes POST /recalculateInvoice
7 minRPC-style endpoints aren't evil — they're the right call when the operation isn't really a resource mutation.
Your mobile team wants GraphQL
8 minGraphQL solves over-fetching and under-fetching for clients; REST solves cache and infrastructure leverage. Pick based on who pays which cost.
Nobody uses HATEOAS — here's why
7 minHATEOAS is REST's original vision for discoverability, but in practice, clients hardcode URLs and read docs — so its real value shows up in narrow, high-leverage places.
Phase 4Ship A Versioned, Paginated API Design
Ship a versioned, paginated API design doc
Decide your versioning scheme
8 minDecide your versioning scheme
Design the list endpoint
9 minDesign the list endpoint
Write the API design doc
12 minWrite the API design doc
Frequently asked questions
- What's the difference between PUT and PATCH in REST?
- This is covered in the “REST API Design Principles” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- How do you version a REST API without breaking clients?
- This is covered in the “REST API Design Principles” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- Is REST still relevant when GraphQL exists?
- This is covered in the “REST API Design Principles” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- What does 'HATEOAS' mean and does anyone actually use it?
- This is covered in the “REST API Design Principles” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- How should I paginate a REST endpoint that returns thousands of records?
- This is covered in the “REST API Design Principles” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
Related paths
🐳Docker Containers Basics
Build the mental model first, then the commands — from containers vs VMs through images, layers, volumes, and networking to composing a multi-service app.
🧪Property-Based Testing
Go beyond example-based tests — learn to express what your code should always do, then let a framework find the inputs that break it.
🦀Rust's Ownership Model
Build a working mental model of Rust's ownership system — from stack vs heap intuition through borrow checker mastery — so you can read and write Rust without fighting the compiler.
💻Elixir Pattern Matching
Stop reading `=` as assignment and start using it as Elixir's core flow-control tool — through function heads, guards, and `with` — until you can rewrite a tiny command parser without a single `if`.