Designing Resource URLs

URLs name things

In REST, a URL identifies a resource — a thing — and not an operation upon it. The HTTP method supplies the verb, which means the path itself should read naturally as a noun. /customers/88 names a customer; what you actually do with that customer depends entirely on whether you GET, PATCH, or DELETE it, not on the path.

This separation is precisely why well-designed APIs feel so learnable in practice. Once you know the resources an API exposes, the URLs become predictable enough that you can often guess them correctly. Understanding the convention also lets you read someone else's API quickly, getting your bearings even before you open their documentation in any detail. The path tells you the noun, the method tells you the verb, and together they are unambiguous.

Naming conventions

A handful of naming conventions recur across nearly all well-designed APIs, and following them makes yours feel familiar to newcomers. Collections use plural nouns — /invoices, never /invoice. A single item then sits under its collection, addressed by its identifier: /invoices/inv_12. Words are kept lowercase throughout, and any multi-word name uses one consistent separator applied everywhere.

/v1/customers
/v1/customers/cus_88
/v1/customers/cus_88/invoices

Consistency matters far more than which particular choice you make at the outset. Once an API settles on plural, lowercase, hyphenated-or-underscored names, applying that decision uniformly across every endpoint is what makes the whole surface feel coherent and intentional rather than assembled piecemeal by different hands.

Expressing relationships

Nesting in the path is how you show that resources relate to one another. /customers/88/invoices reads naturally and immediately as "the invoices belonging to customer 88", scoping that collection cleanly to its parent. The structure of the URL mirrors the real structure of the data, which keeps related things grouped together in a way that is easy to reason about.

Avoid the temptation to nest too deeply, though, because the cost grows quickly. Paths several levels long become awkward to read, tedious to construct, and brittle if the hierarchy ever changes underneath them. A widely followed guideline is to nest only one level for the immediate relationship and to reach more distant resources through their own top-level collection wherever that reads more cleanly.

Keep verbs out

A frequent and tempting anti-pattern is encoding the action directly into the path — endpoints like /getCustomer or /deleteInvoice. This duplicates exactly what the HTTP method already conveys perfectly well, and in doing so it quietly breaks the clean noun-based model that makes REST predictable. Prefer GET /customers/88 and DELETE /invoices/12 instead, letting the method carry the verb.

Genuine actions that do not map cleanly onto a simple create-read-update-delete lifecycle can usually be modelled as sub-resources rather than as verbs jammed into the path. The aim throughout is always the same: a path that names a thing, paired with a method that describes what is happening to it. Hold to that and your URLs stay legible.

What good looks like

Pulling the threads together, a well-designed URL is a lowercase, plural-collection, noun-based, predictably nested address, with the version stated up front and not a single action verb in sight. When every endpoint across an API follows the very same pattern, callers can frequently guess a correct URL before they have even read the documentation, which is the clearest possible sign of a coherent design.

For a closer look at where parameters attach to these clean paths — and which kind belongs in the path itself versus the query string — read query vs path vs body params, the natural next step from URL structure.