Resources and URIs

A REST API is organised around resources: the things a client cares about — an order, a customer, an invoice, the list of a customer's orders. Each resource is identified by a URI, and the HTTP method says what the client wants done to it. The URI is the noun; the method is the verb. Put the verb in the URI as well and you have two places that say what is happening, which is how APIs end up with both POST /deleteOrder and DELETE /orders/7.

Collections and items

Almost every resource comes in two shapes:

GET  /orders          # the collection: list, filter, page
POST /orders          # add to the collection; the server picks the id
GET  /orders/7        # one item
PATCH /orders/7       # change part of it
DELETE /orders/7      # remove it

Conventions that most public APIs agree on: plural nouns for collections (/orders, not /order), lowercase with hyphens between words (/line-items), and no file extension — the format is negotiated with the Accept and Content-Type headers, not baked into the path. These are conventions, not rules of HTTP, but a reviewer will notice an API that breaks them inconsistently.

Two facts that are rules: per RFC 3986 the scheme and host of a URI are case-insensitive but the path is case-sensitive, so /Orders and /orders are different URIs; and /orders and /orders/ are different URIs too. Pick one form and redirect or reject the other — do not let both silently work for some routes and not others.

Try it

The router below maps a method and a path onto a handler. The same URI reaches different handlers depending on the method, and a path that exists but does not support the method is a different failure from a path that does not exist at all.

Nesting means containment

/customers/42/orders reads well when an order genuinely belongs to one customer and the client is asking "this customer's orders". It is a filtered view of /orders, and that is fine. The trouble starts deeper: /customers/42/orders/7/items/3 forces the client to know the customer id just to address an item, and breaks the day an item moves. A good rule is one level of nesting at most, with every item also reachable at its own top-level URI (/orders/7).

Actions that are not CRUD

"Cancel an order" or "send an invoice" do not map neatly onto create, read, update and delete. Two honest options, both without a verb in the path:

• Change state: PATCH /orders/7 with {"status": "cancelled"}, when cancelling is really just a field changing and the server validates the transition.
• Create a sub-resource: POST /orders/7/cancellation, when the action has its own data (a reason, who did it, when) and its own lifecycle you may want to read back later with GET.

Query strings filter, paths identify

/orders?status=open is the orders collection, filtered. The path identifies which resource; the query string narrows or shapes what comes back. An id belongs in the path, a filter in the query.

Common mistakes

• Verbs in paths (/getOrders, ): the method already carries that meaning, and the URI stops identifying one resource.