routes-and-naming

URLs Are Your API's User Interface

A URL is the first thing every developer sees when integrating an API. Stripe, GitHub, Twilio, and Shopify all converge on the same core patterns: plural nouns, shallow nesting, snake_case fields, and zero verbs in paths. These are not style preferences — they are battle-tested conventions from APIs handling billions of calls daily. Deviation from them forces every consumer to learn your exceptions instead of relying on muscle memory.

Resource Naming: Plural Nouns, No Verbs

The HTTP method is the verb. The URL names the resource. Always use plural nouns for collections.

Rules:

• Use plural nouns for every collection: /users, /orders, /products
• Use singular only for true singletons: /users/{id}/profile (one profile per user), /health, /configuration
• Never embed verbs in URLs: POST /orders not POST /createOrder
• Never embed operations: DELETE /users/123 not GET /deleteUser?id=123

Good:

GET  /orders              # collection of orders
GET  /orders/789          # single order
GET  /users/42/profile    # singleton sub-resource
POST /v1/customers        # Stripe pattern

Bad:

GET  /order               # singular collection name — ambiguous
GET  /getUsers            # verb in URL
POST /createOrder         # verb in URL; HTTP method already says "create"
GET  /getUserById/42      # verb + redundant description

Real-world evidence: Stripe uses GET /v1/customers, GitHub uses GET /repos/{owner}/{repo}/issues, Twilio uses GET /Accounts/{sid}/Messages, Shopify uses GET /admin/api/2026-01/products.json. All plural nouns.

Nesting Depth: Maximum 2 Levels

Limit URL hierarchy to /{resource}/{id}/{sub-resource}. Never exceed /{resource}/{id}/{sub-resource}/{id} in production routes.