Verbs in Paths: /getUser and /createOrder

A verb in the path repeats what the method already says and hides the resource underneath.

A path that contains a verb, such as /getUser or /createOrder, describes an operation instead of naming a resource, and repeats what the HTTP method should say. It hides how the operations relate, multiplies paths, and invites the wrong method, such as a GET that deletes.

The symptom. A list of endpoints that reads like a list of functions: /getUser, /getUsers, /updateUser, /deleteUser, and before long /getUserOrders and /getActiveUsersByRegion. Every new need adds a path, and nobody can guess the next one.

Five operations as verb paths and as resource paths

Verb pathsone path per operation

GET /getUser?id=7, POST /createUser, POST /updateUser, GET /deleteUser?id=7, GET /getUserOrders?id=7. Five paths, a delete on GET, and nothing that says they concern the same thing.

Resource pathsthe method is the verb

GET /users/7, POST /users, PATCH /users/7, DELETE /users/7, GET /users/7/orders. Two resources, each operation guessable from the others, and every method used for its meaning.

Why it happens. The API is designed as remote functions, one per thing the client needs, with HTTP as the transport. That style has a name, remote procedure call, and it is a legitimate choice; but mixed into a resource API it gives the worst of both.

What it costs. Caches, retry libraries and gateways cannot tell reads from writes by the path, so they rely on the method, and a verb path often carries the wrong one. Clients cannot predict paths, so every call needs the documentation.

What to do. Name the noun and let the method be the verb. Actions that are genuinely not create, read, update or delete, such as cancelling, are the honest exception, modelled as a sub-resource or a clearly marked action path with POST.

← → move through sections and cards