2. Resource Naming

Good resource names make an API intuitive to use. Follow a small set of conventions and your URLs will read naturally.

Use Plural Nouns for Collections

A collection endpoint always uses the plural form of the resource name. The singular resource lives at the same path with its identifier appended:

GET /products          # list all products
GET /products/42       # retrieve product 42
POST /products         # create a new product

Model Hierarchy with Sub-Resources

When one resource logically belongs to another, nest it as a sub-resource. This makes the ownership relationship clear from the URL alone:

GET /orders/42/items       # list all items in order 42
GET /orders/42/items/5     # retrieve item 5 within order 42
POST /orders/42/items      # add an item to order 42

Keep nesting shallow — two levels is usually the maximum. If you find yourself writing /a/1/b/2/c/3, consider whether the deepest resource can be accessed directly via its own top-level endpoint (e.g. GET /items/5).

Avoid Verbs

The HTTP method already communicates the action. Adding verbs to the URL is redundant and breaks the noun-based convention:

# Correct
POST /orders

# Incorrect
POST /createOrder
POST /orders/submit

Use Hyphens, Not Underscores or CamelCase

When a resource name contains multiple words, separate them with hyphens. Hyphens are easier to read in URLs and are friendlier to search engines:

# Correct
/shipping-addresses

# Avoid
/shippingAddresses
/shipping_addresses

Keep Names Lowercase

URLs are case-sensitive in most servers. Stick to lowercase throughout to avoid confusion and potential routing bugs.