In the previous lesson we fixed the working method and decided, with judgement, which nouns of the Aroma Store domain deserve to be resources. Now comes the next step: giving them an address. The URI is the most visible and most long-lived part of an API —clients write it into their code, save it in bookmarks, paste it into tickets— and that is also why it is the most expensive thing to change. This lesson establishes the naming rules, settles when to nest and when not to, chooses the type of identifier and tackles the problem that no CRUD solves on its own: how to model actions such as paying for an order or moderating a review. We will finish with the complete URI map of Aroma Store, which the rest of the module will take as given.

1. What a resource is and what a URI is
2. Nouns, not verbs
3. Collections and elements
4. Naming rules
5. Hierarchy and nesting
6. Singleton resources
7. Path parameters versus query parameters
8. Identifier design
9. Actions that are not CRUD
10. Aroma Store's URI map

Let us recall the definition from 01-04: a resource is anything with identity that it makes sense to operate on; the URI is its stable identifier; the representation is one of its possible concrete forms (the JSON that travels, the PDF, the HTML).

Three practical consequences that govern this entire lesson:

• A resource can have several representations (/orders/ord_5001/invoice in JSON or in PDF), but it keeps a single URI. The representation is chosen by content negotiation (02-05), not by changing the URL with .pdf.
• A URI identifies, it does not describe the operation. What you do with the resource is stated by the method (02-03).
• URIs should outlive internal changes. If /coffees/cof_001 stops working because the database has been refactored, we have broken the contract.

The most quoted rule of REST design, and the one most often broken:

Why it matters, beyond aesthetics:

• The method is already the verb. GET /getCoffees repeats the verb and, worse, allows the incoherent POST /getCoffees.
• HTTP's semantics are lost. GET /deleteReview is a functional disaster: a search engine or a browser prefetch could delete reviews while following links, because GET is safe by definition (02-03).
• Predictability is lost. With verbs, every endpoint has to be memorised: getCoffees, fetchOrders, listReviews, readCustomer.

Watch out for one important nuance: identifiers in the code do use verbs (getCoffees(), createOrder()), as the style guide states. What carries no verb is the URI.

Every resource-oriented API is structured around two shapes:

• Collection: a set of resources of the same type. /coffees.
• Element (or individual resource): a specific member. /coffees/cof_001.

The pattern reads from left to right like a navigation path:

Each level alternates collection → element → collection → element. If your URI breaks that alternation (/customers/orders/cus_842), there is almost always a design error.

And each shape admits different operations, which anticipates 02-03:

These are the rules Aroma Store adds to its style guide.

/coffees, /customers, /orders, /reviews, /carts. Always plural, even when it sounds odd, because the alternative —singular for the element and plural for the collection— forces you to remember two forms per resource.

The only exception is singletons (section 6), which by definition are not collections.

The path component of a URL is case-sensitive (unlike the host name). /Coffees and /coffees are two different resources as far as the standard is concerned, and accepting both doubles the surface of the contract and ruins caching.

Reasons: it is the dominant convention on the web, it is more readable and search engines treat the hyphen as a word separator (relevant if part of the API is indexed or if you share documentation links). Notice the deliberate asymmetry: kebab-case in the URI, camelCase in the JSON. It is an apparent inconsistency, but these are two worlds with their own settled conventions; what matters is that each world is consistent with itself.

The format is a question of representation, and it is negotiated with headers (02-05). Adding .json mixes identity and format: if you add XML or PDF tomorrow, every resource has three URIs for the same thing.

/coffees and /coffees/ are technically different paths. Pick one —Aroma Store uses no trailing slash— and redirect the other with a 301 (02-04) instead of serving both.

The name of the class, the table or the implementation pattern is none of the consumer's business. Watch out for /api too: if the host is already api.aromastore.example, repeating it in the path is redundant.

No accents, ñ, spaces or capitals in the path segments you control. That is why the collection is /origins and never /orígenes: even though modern browsers encode non-ASCII characters, in practice they end up showing as /or%C3%ADgenes in logs, curl examples and old clients.

Nesting expresses belonging: /coffees/cof_001/reviews are the reviews of that coffee.

Nest a sub-resource only if it makes no sense outside its parent, or if the belonging relationship is the natural way of reaching it.

Examples in Aroma Store:

A rule that saves a lot of grief: do not go beyond /collection/{id}/subcollection/{id}. Past that point the URI becomes illegible, it couples the client to a hierarchy that may change and it forces you to validate long chains of belonging.

When you need to go deeper, cut the hierarchy and use a top-level collection with a filter:

The same resource can be reachable through two paths if each one serves a different use case. In Aroma Store:

Rules to stop this becoming a problem:

• The element lives at one single canonical URI: /reviews/rev_101. The nested form is only for listing and creating.
• The representation's self link always points at the canonical one, so that two paths do not generate two identities.
• Nested creation is more convenient: POST /coffees/cof_001/reviews does not need to repeat coffeeId in the body, because it is already in the URI.

A singleton is a resource of which only one instance exists in its context. It has no collection and no identifier of its own, and that is why it goes in the singular.

A singleton typically admits GET, PUT and sometimes DELETE, but not POST (there is no collection to add to), with the exception of singletons that model an action, which do use POST (section 9).

Beware of the badly used singleton: /customers/cus_842/address is fine if the customer can only have one; the moment they can have several it becomes /customers/cus_842/addresses and that is a breaking change (02-07). If in doubt, start with a collection.

The most common confusion in URI design. The rule is simple and almost never fails:

The path identifies the resource. The query string modifies how the collection is returned.

A side-by-side example:

Two nuances worth knowing:

• A filter that returns a single element is still a collection. GET /coffees?name=Ethiopia Yirgacheffe returns {"data": [...], "total": 1}, not the bare object, and it returns 200 with an empty list if there are no matches (not 404). The reason: the "filtered collection" resource exists even when it is empty.
• Query parameters affect caching. Every different combination is a different URL and therefore a different cache entry. That is one more argument for not multiplying parameters needlessly (04-06).

The identifier you put in the URI is contract forever. The options:

cof_001, cus_842, ord_5001, rev_101, crt_77, inv_88, evt_9f2c. It is the style Stripe made popular and the reasons are very practical:

1. Self-describing. When you read a log or a ticket, ord_5001 is understandable without context. With a bare 5001 you do not know what it belongs to.
2. Impossible to cross types. If someone sends POST /v1/orders with {"customerId": "cof_001"}, the server spots the wrong prefix and responds 400 with invalid_data, instead of creating an incoherent order.
3. Opaque by contract. The documentation says so explicitly: the identifier is an opaque string, do not parse it, do not assume a length, do not assume that the numeric part is sequential. That way we can migrate tomorrow to cof_01HQ8ZK... without breaking anyone.

In production, the part after the prefix should be random and non-sequential. The cof_001 and ord_5001 of this course are didactic; in a real shop, publishing sequential identifiers has two problems:

• Business information leakage. A competitor who places an order on Monday and another on Friday knows how many orders you received that week. It is the classic German tank problem.
• Enumeration. With sequential ids, walking ord_5001, ord_5002, ord_5003… is trivial. A third party being able to read other people's orders is an authorisation failure, not an id failure —it is called IDOR and it is covered in 04-02— but guessable ids turn an isolated flaw into a mass leak. The rule is: always authorise, and on top of that do not make it easy.

About slugs: they are excellent for the public web (aromastore.example/coffees/ethiopia-yirgacheffe) and bad as API identity, because they change. If you want them, the usual pattern is for the slug to be one more field of the representation and a filter (?slug=ethiopia-yirgacheffe), while the canonical URI remains the opaque id.

Here is the most interesting design problem of the lesson. Many business operations are not "create, read, update, delete":

• Paying for an order.
• Cancelling an order.
• Approving or rejecting a review.
• Emptying a cart.
• Resending the confirmation email.

There are three strategies, and it is worth understanding all three before choosing.

It is acceptable when the transition is purely a data change, with no logic and no side effects.

You look for the noun behind the verb: approve → an approval; pay → a payment; cancel → a cancellation. That noun is a resource that is created with POST.

The advantages are exactly the ones we were after:

• No verbs in the path: approval is a noun and the verb is supplied by POST.
• The action can carry its own body: the reason for the rejection, the payment reference, the amount.
• The action is a queryable resource: GET /v1/orders/ord_5001/payment returns the payment that was made, with its date and its reference.
• It is authorised separately: permission to create /approval is different from permission to edit the review (04-03).
• It leaves room for idempotency: being a well-delimited POST, you can require an Idempotency-Key on it (02-03).

And Aroma Store's action map ends up like this:

Notice the last row: before inventing a sub-resource, check whether a standard method already expresses it. Emptying the cart is exactly "delete all its items", so DELETE /carts/crt_77/items is more natural than a POST /carts/crt_77/emptying. It is the exception to the rule in section 3 about not using DELETE on collections, and it is legitimate because here the collection is scoped to one specific cart and deleting it wholesale is a genuine business operation.

This is the outcome of the lesson and the map that the rest of the module will take as given. The methods appear to give context; their exact semantics are 02-03 and the response codes are 02-04.

Decisions noted down so we do not forget them:

• There is no POST /v1/reviews: a review is always born attached to a coffee, so it is only created at /coffees/{coffeeId}/reviews. The flat view is read-only and serves the internal panel.
• There is no DELETE /v1/orders/{id}: an order is not deleted, it is cancelled. The accounting record is sacred.
• /v1/origins has been considered and discarded for v1: the origin is an attribute and is filtered with ?origin=. If it ever has data of its own (altitude, cooperative, photo), it will become a collection and can be added without breaking anything (02-07).

• Putting the verb in the path "just for this one operation". You start with one exception and you end up with twenty. If you need an action, look for its noun.
• Nesting out of habit. /customers/cus_842/orders/ord_5001 forces the server to validate that the order belongs to that customer and forces the client to know two ids to fetch one thing. Nest to list, use the canonical URI for the element.
• Using the query string to identify. /coffees?id=cof_001 breaks caching by URL, complicates self links and does not allow sub-resources.
• Adding .json at the end. It mixes identity and format; that is what Accept is for.
• Pluralising badly. /coffees and /coffee/cof_001 living side by side is the most frequent documentation bug in the world.
• Exposing the database id out of convenience. Changing engine or merging environments will force you to break the contract. An opaque id leaves you free.
• Tip: write the URIs before the code and read them out loud. If reading /orders/ord_5001/cancellation with POST is understandable without explanation, it is well designed.
• Tip: keep a table like the one in section 10 in the repository. It is the index of the contract and the place where any new endpoint gets discussed before it exists.

A team has proposed these paths for Aroma Store. Correct them and justify each change.

Aroma Store wants a customer to be able to gift an order: when confirming it they give the recipient's email address and a message, and the system sends a notification and hides the price on the delivery note.

Model this feature with the three strategies from section 9 (PATCH, verb in the URI, sub-resource), show the HTTP request for each one and pick the one that fits the style guide, justifying your choice.

For each need, decide the URI and say whether you nested it or not and why:

1. The internal panel wants to see all the sold items of coffee cof_001 in the last month.
2. Aroma Mobile wants the reviews written by customer cus_842.
3. SwiftShip wants to update the shipment status of order ord_5001.
4. The SPA wants the price change history of cof_001.

Solution 1

Solution 2

Strategy A — PATCH on the order:

It works, but sending the notification is left as a hidden side effect of a field change, and there is nowhere to check afterwards whether the notification was sent.

Strategy B — verb in the URI:

Crystal-clear intent, but a verb in the path: it breaks the style guide and opens the door to giftWithoutNotice.

Strategy C — sub-resource (the chosen one):

This is the chosen one: a noun (gift), its own body for the action's parameters, queryable afterwards with GET, and cancellable with DELETE /v1/orders/ord_5001/gift as long as the order has not shipped. It fits exactly alongside /payment, /cancellation and /approval.

Solution 3

1. GET /v1/order-items?coffeeId=cof_001&dateFrom=2026-02-14 — not nested. What is being searched for cuts across every order, so the /orders/{id}/items hierarchy is no use: a flat top-level collection queryable with filters is needed. Beware the temptation to write /v1/orders/items: it would collide with /v1/orders/{orderId}, because the router cannot tell an id called items from a fixed segment. (A reasonable alternative: a reporting resource /v1/sales?coffeeId=..., if the panel needs aggregates rather than individual items.)
2. GET /v1/reviews?customerId=cus_842 — not nested under the coffee, because the criterion is the author. Nesting it as /customers/cus_842/reviews would also be defensible if "my reviews" were a screen of its own in Aroma Mobile; both obey the rule, and in that case it would be wise to pick just one so as not to duplicate contract.
3. PUT /v1/orders/ord_5001/shipment — nested and a singleton: a shipment does not exist outside its order and there is only one. PUT because SwiftShip sends the shipment's complete state on every update (02-03).
4. GET /v1/coffees/cof_001/price-history — nested: the history makes no sense outside its coffee and it is read-only. Note the kebab-case in the compound word. If the history were queried globally across the whole catalogue, it would become /v1/price-history?coffeeId=cof_001.

URIs are the public and most long-lived face of the API, and you now have concrete rules for designing them: plural, lowercase nouns, kebab-case for compound words, no extensions and no verbs, nesting only when it expresses real belonging and never beyond two levels, singulars for singletons that are genuinely unique, identification in the path and collection modification in the query string, and opaque prefixed identifiers that do not leak business information. Above all you have solved the problem that throws everybody: actions that are not CRUD are modelled as sub-resources created with POST, which gives each action its own body, later queryability and independent authorisation. Aroma Store's URI map is settled.

We now know which resources exist and where they live. What is missing is stating precisely what can be done with each of them. In the next lesson, 02-03 HTTP Methods, we will walk through GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS applied to this map; we will understand why safety and idempotency are far more than theory when SwiftShip retries a request or a customer clicks the pay button twice; we will compare PUT against PATCH with JSON Merge Patch and JSON Patch in depth; and we will design the idempotency keys for paying an order.