Naming & URL Design

URL design is part of your public contract

Clients will copy your URLs into code, docs, dashboards, and support tickets. A consistent naming strategy reduces confusion and prevents breaking changes.

Use nouns, not verbs

• Good: /api/users, /api/orders
• Avoid: /api/getUsers, /api/createOrder

Use plural for collections

Pick a convention and stick to it. Plural collections are common and predictable.

GET /api/users
GET /api/users/42

Sub-resources and nesting (use sparingly)

Nesting is useful when the child does not make sense without the parent. Avoid deep nesting that becomes unmaintainable.

GET /api/users/42/orders

Consistency rules that matter

• Choose one casing style (kebab-case is URL-friendly).
• Keep resource names stable and short.
• Prefer IDs in paths, not in query strings for single resources.
• Use query parameters for filtering and sorting.

Action endpoints (sometimes necessary)

Some actions are not CRUD (e.g., /reset-password). Model them carefully: either as a sub-resource (preferred) or a clear action endpoint.

POST /api/users/42/password-reset
POST /api/invoices/77/send

Common mistakes

• Inconsistent naming (sometimes singular, sometimes plural)
• Deep nesting that mirrors database relations
• Mixing multiple concepts in one endpoint

Checklist

• URLs are nouns and consistent across the API.
• Collections are plural; single resources use an ID segment.
• Actions are modeled intentionally (not random verbs everywhere).