How should REST API URLs be structured?

Name resources with plural nouns and express relationships through path hierarchy - the HTTP method, not the URL, supplies the verb.

The single rule that fixes most messy APIs: a URL is a noun, the HTTP method is the verb. You never write the action into the path, because the method already says it. DELETE /users/123 is the delete action - putting "delete" in the URL too is redundant and breaks the convention.

Use plural collection names and let nesting show ownership:

• /users - the whole collection of users
• /users/123 - one specific user (the 123 identifies which)
• /users/123/orders - the orders belonging to user 123
• /users/123/orders/456 - one specific order under that user

Compare the anti-patterns, which smuggle the action into the path:

• /getUser/123 - the verb "get" belongs in the GET method, not the URL
• /user/delete/123 - "delete" belongs in the DELETE method

Memory tip: read a good REST URL out loud as "the order 456, of user 123" - it should sound like a path through a tree of nouns. If you hear a verb, the design has leaked an action into the address. Keep filtering and sorting out of the path too; those go in the query string, e.g. /users?sort=name&limit=10.