principletypescriptTip

API Naming Conventions: Use nouns for resources, verbs for actions

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

restresourcenounverbendpointurlkebab-case

Problem

Inconsistent API endpoint naming makes APIs hard to understand and predict. Using verbs in resource URLs (e.g., /getUser, /createOrder) breaks REST conventions and confuses consumers.

Solution

Use plural nouns for collection endpoints (/users, /orders), singular nouns for nested identifiers (/users/:id). Reserve verbs only for non-resource RPC-style actions (/users/:id/activate). Keep names lowercase and hyphen-separated for multi-word resources (/payment-methods).

Why

REST is resource-oriented. Nouns model the state consumers operate on; HTTP verbs (GET, POST, PUT, DELETE) model the actions. Mixing verbs into URLs creates redundancy and breaks client generation tooling.

Gotchas

Do not use camelCase or snake_case in URL segments — use kebab-case.
Avoid deeply nested paths beyond two levels of nesting (/users/:id/orders/:orderId is fine; /users/:id/orders/:orderId/items/:itemId/variants is not).
Action endpoints like /activate are acceptable when no resource identity maps cleanly to the action.

Code Snippets

Good vs bad endpoint naming

// Bad
app.get('/getUsers', handler)
app.post('/createOrder', handler)
app.put('/updateUserProfile/:id', handler)

// Good
app.get('/users', handler)
app.post('/orders', handler)
app.put('/users/:id/profile', handler)
app.post('/users/:id/deactivate', handler) // action verb only when no resource maps

Revisions (0)

No revisions yet.