HTTP Foundations and REST PrinciplesLesson 1.4

REST resource naming and URL design best practices

resource naming, nouns vs verbs, plural vs singular, nested resources, URL hierarchy, query parameters, filtering

REST URL Design

URLs identify resources — nouns, not verbs. The HTTP method expresses the action. Putting verbs in URLs is the most common REST naming mistake.

Core Rules

Use plural nouns for collections: /users, not /user. Use the resource ID for singletons: /users/42. Use nested paths to express ownership: /users/42/orders means orders belonging to user 42.

// Good
GET    /articles           → list articles
POST   /articles           → create article
GET    /articles/7         → get article 7
PUT    /articles/7         → replace article 7
DELETE /articles/7         → delete article 7
GET    /articles/7/comments → list comments on article 7

// Bad
GET  /getArticles
POST /createArticle
GET  /article/delete/7

Query Parameters

Use query strings for filtering, sorting, and pagination — never for identifying a resource.

GET /articles?status=published&sort=createdAt&order=desc&page=2&limit=20

Keep nesting shallow. If you need more than two levels (/a/:id/b/:id/c), the design usually indicates a missing top-level resource. Expose /c/:id directly and filter by parent IDs via query params.