Resources, Nouns and URL Structure — API Design & Best Practices

A REST-style URL names a thing, not an action. `/orders/482` identifies a specific order; what you do to it — read it, update it, delete it — is expressed by the HTTP method, not by the URL. This sounds like a small convention, but it's the load-bearing idea the rest of resource modeling depends on: once a URL is a noun, every consumer can predict its shape for any operation without memorizing a separate verb-based endpoint for each one. `GET /orders/482`, `PATCH /orders/482`, `DELETE /orders/482` are all guessable from knowing one of them; `/getOrder/482`, `/updateOrderStatus/482`, `/removeOrder/482` are three separate things to memorize with no shared structure to lean on.

The discipline breaks down in two common ways. The first is verbs sneaking into URLs — `/orders/482/cancelOrder` — which usually means the team reached for an action when a state transition or a sub-resource would model the same thing more consistently. The second is resources that don't map to anything a consumer would recognize as a real, addressable thing — an endpoint like `/processOrderBatch` that isn't really about a resource at all, but a one-off operation dressed up as if it had a URL to identify, when what it actually needs is to be modeled honestly as an action on a genuine resource, which this lesson and the next will both return to.

Getting resource modeling right is worth the up-front thought because URL structure is one of the most visible, most-referenced parts of an API — it appears in every log line, every error report, every piece of documentation, and every conversation between engineers debugging an integration. A confusing resource model doesn't just make the API harder to use; it makes every conversation about the API harder to have.

Analogy🏏Cricket

🏏 Think of it like cricket: A stadium's seating and directional signage is organized entirely around nouns — Stand A, Block 12, Row F, Seat 23 — a strict hierarchy of places, never around verbs like "walk to your seat" or "find the exit." A spectator holding a ticket that says Stand A, Block 12, Row F, Seat 23 can navigate the entire stadium using nothing but that address and the consistent signage pointing toward each level of it, without ever needing separate instructions for how to get to a seat versus how to get to a concession stand versus how to get to a restroom — because all of those are also just addressable places within the same nested structure, reached the same way. Now imagine a stadium that instead posted signs reading "Go To Your Seat This Way" in one corridor and "Exit Route For Match End" in another, with each sign describing an action rather than naming a place, and no consistent structure connecting them. A spectator would need a completely different, memorized instruction for every kind of movement through the venue, because nothing about the signage system is composable — knowing how to find your seat tells you nothing about how to find the exit. A URL structure built around nouns works exactly like the stadium's place-based signage: `/orders/482`, `/orders/482/items`, `/orders/482/items/9` are all just addresses within a consistent hierarchy, and once a consumer understands the pattern, they can navigate to anything that fits it without new instructions for each case.