REST API Design
The problem
Once a server can respond to requests, its interface needs to be predictable enough that clients (including ones you'll never meet) can guess how to use it correctly — REST is a set of conventions for organizing an API around resources and standard HTTP methods so its shape becomes learnable, not arbitrary.
Why now
Building an HTTP server showed how to respond to any request, but not how to design a coherent set of them. REST supplies that missing design discipline — a convention for mapping types-and-values' idea of 'a thing with a type' onto URLs and HTTP methods in a consistent, predictable way.
Mental model
REST models everything as a resource (a noun, addressed by a URL) acted on by a small, fixed set of standard verbs (the HTTP methods) instead of inventing a new verb for every action. GET /orders/42 always means 'give me order 42,' never 'do something to it' — that discipline is what makes an unfamiliar REST API guessable from its URL structure alone.
Requires
- Building an HTTP ServerBackend Engineering
REST is a design convention for the requests and responses a server already knows how to send and receive; you need a working server before there's an interface worth designing well.
- Types & ValuesProgramming Fundamentals
A REST resource is fundamentally a typed entity (a user, an order) with a defined shape; the resource-oriented design REST relies on is a direct application of thinking in terms of types.
Unlocks
Used in
- Nearly every public and internal HTTP API built today
- OpenAPI/Swagger specifications, which formally describe a REST API's resources and methods
- API client libraries and SDKs generated directly from a well-designed REST structure
- GraphQL and RPC-style APIs, often explained by contrast with REST's resource-oriented model
Projects
- Design and implement a REST API for a small domain (e.g. a bookshelf) with proper resource URLs and HTTP methods for create/read/update/delete
- Take a poorly designed API (verbs in URLs, inconsistent methods) and redesign it following REST conventions, explaining each change
Examples
- POST /orders creates a new order; GET /orders/42 retrieves it; PATCH /orders/42 updates it; DELETE /orders/42 removes it — one URL, four standard verbs
- GET /getUserData?id=42 violates REST conventions by encoding an action ('get') into the URL instead of using the GET method itself
Resources
Mastery checklist
- I can design resource-oriented URLs for a given domain
- I can map create/read/update/delete operations onto the correct HTTP methods
- I can explain why REST prefers nouns in URLs and verbs as HTTP methods
- I can critique and improve a non-RESTful API design