Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 39 ยท Designing Resources and Endpoints

Resource Naming and URL Design

Design clean REST URLs: use plural nouns, no verbs, sensible hierarchy, kebab-case, stable identifiers and slugs, with a URL linter and a route matcher to try.

Good REST design starts with a list of nouns. Before you write any code, ask: what are the things my API is about? Books, authors, orders, invoices, comments. Each becomes a resource with a URL. The HTTP methods supply the verbs, so URLs themselves should almost never contain verbs.

URLs are part of your public contract. Once clients use them, changing them is painful, so a little care in naming pays off for years.

The core rules

  1. Use nouns, not verbs. GET /books, not GET /getBooks.
  2. Use plural names for collections. /books is the collection, /books/42 is one item. Pick plural and stay consistent: do not mix /book and /authors.
  3. Let the method express the action. POST /books creates, DELETE /books/42 deletes.
  4. Use lowercase and hyphens. /order-items, not /orderItems or /Order_Items. URL paths can be case-sensitive, and hyphens are easier to read than underscores.
  5. No trailing slash, no file extension. /books/42, not /books/42/ or /books/42.json. Use the Accept header for formats (see content negotiation).
  6. Show hierarchy only where it is real. /authors/7/books reads as "books belonging to author 7".
  7. Keep URLs stable. Do not embed things that change, such as a user's display name.
flowchart LR
    A["/authors"] --> B["/authors/7"] --> C["/authors/7/books"] --> D["/authors/7/books/42"]

Collection, item, nested collection, nested item.

Bad Better Why
GET /getAllUsers GET /users Verb in the URL
POST /users/create POST /users POST already means create
GET /user/7 GET /users/7 Collections are plural
GET /Users/7/ GET /users/7 Case and trailing slash
GET /users/7/delete DELETE /users/7 Unsafe action on GET
GET /api/v1/product_categories GET /api/v1/product-categories Hyphens read better

Identifiers

The identifier at the end of an item URL needs thought:

  • Auto-increment integers (/orders/1042) are simple, but they leak how many records you have and are easy to guess. That matters for security, so pair them with authorization checks.
  • UUIDs (/orders/3f2b...) are unguessable and can be generated by the client or any server. They are long.
  • Slugs (/articles/rest-api-basics) are friendly and good for SEO, but they change when titles change. Use them as an additional lookup or keep the old slug redirecting.
  • Composite natural keys (/countries/de) work when the code is truly stable, such as ISO country codes.

Whatever you choose, treat IDs as opaque strings in the API, even if they are numbers inside. Clients should not do arithmetic on them. The next lessons use strings in the JSON for exactly this reason.

Singletons and special resources

Some resources exist once per context, so they have no id: the current user (/me), a user's profile (/users/7/profile) or settings (/settings). They are still nouns. A GET /me shortcut is a popular convenience for "the user identified by my token".

Searching and reports are nouns too: /search?q=dune, /reports/monthly-sales. When something really is a process and not a thing, make the process a noun (/payments, /exports) or use an action sub-resource. Relationships and actions covers this case.

A URL linter

Rules are easier to remember when a tool checks them. This script lints a list of paths and reports which rules each breaks.

Node.js Lint your API paths

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The linter is deliberately simple, but real teams do the same with API linting tools in CI so that new endpoints follow the style guide automatically.

Matching URLs to resources

On the server, a route table maps a path pattern to a handler. Modern Node includes the standard URLPattern class, which supports named parameters like :id:

Node.js Routing with URLPattern

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the three outcomes: a match, 405 when the path exists but not for that method, and 404 when no path matches at all.

Versioning in the URL (preview)

A prefix such as /v1/books is a common way to evolve an API without breaking old clients. Whether it belongs in the path, a header or a media type is a design choice you will explore in the versioning lesson later in this course. For now, remember that the prefix is a separate part from the resource path and stays the same for every endpoint.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which URL follows REST naming conventions for creating a user?

    The collection URL is a plural noun; the POST method already means create.
  2. 2. Why should you avoid putting a user's display name in their resource URL?

    Stable identifiers keep URLs valid for years. Names and titles are not stable.
  3. 3. Which is better style for a multi-word collection?

    Lowercase words joined with hyphens are the usual convention.
  4. 4. What is a good use of a URL like /me?

    /me is a convenient singleton that refers to the current authenticated user.

Summary

  • Name resources with plural nouns; let HTTP methods carry the verbs.
  • Use lowercase, hyphens, no trailing slashes and no extensions.
  • Nest only real parent-child relationships, and keep IDs stable and opaque.
  • Singleton resources like /me and /settings are still nouns.
  • Route tables distinguish 404 (unknown path) from 405 (wrong method).

Next: Designing JSON Payloads