Resource Modelling
Expressing an API as nouns with a consistent hierarchy rather than as verbs, so URLs are predictable and methods carry the semantics.
The discipline is that the URL identifies a thing and the HTTP method says what to do to it:
POST /orders, GET /orders/123, DELETE /orders/123/lines/4. A consumer who knows the resource can
guess the URL, which is most of what makes an API pleasant.
The recurring difficulty is operations that are not obviously CRUD — cancel, approve, refund, publish.
Three defensible answers: model the operation's result as a sub-resource
(POST /orders/123/cancellation), model the state as a field and PATCH it, or accept a controller-style
action (POST /orders/123/cancel) where forcing a noun would be contorted. Consistency matters more
than purity.
Two rules that prevent later pain: keep hierarchies shallow (two levels of nesting is usually enough, and deep nesting couples the URL to a structure that will change), and never let the URL encode information the resource should own.