Designing resources and URLs

Things, not procedures

A URL should name a thing. Verbs belong in the method, so listing, fetching, and deleting a user are one path with three methods rather than three paths.

Nest a path only when the child genuinely belongs to the parent and cannot be addressed without it. Deeply nested paths become unusable the moment a resource needs to be reached another way.

Consistency beats elegance. Plural nouns everywhere, one casing convention, one date format — an API that is predictable is one people can guess correctly.