REST API Naming Conventions

Names shape how developers feel about an API. A clear name explains itself, and a confusing name sends people to the documentation again and again. Consistent naming rules make an API predictable, so users guess correctly before they read a single page.

The Street Sign Picture

Travelers in a new city rely on street signs. Signs with the same style, the same language, and logical order make navigation easy. A city that mixes styles confuses everyone. API names serve as street signs for developers.

Use Nouns for Resources

URLs identify things, and HTTP methods describe actions. Write the thing in the path and let the method carry the verb.

Weak:    POST /createUser
         GET  /getAllUsers
         POST /deleteUser/12

Strong:  POST   /users
         GET    /users
         DELETE /users/12

Use Plural Collection Names

A collection holds many items, so a plural noun reads naturally. Use /books for the list and /books/5 for one item. Pick plural everywhere. Mixing /book and /books forces users to remember which endpoint uses which form.

Choose One Case Style

Place	Recommended Style	Sample
URL paths	lowercase with hyphens	/order-items
Query parameters	lowercase with underscores or camelCase	sort_by or sortBy
JSON fields	camelCase or snake_case	firstName or first_name
Headers	Title-Case with hyphens	X-Request-Id

URLs treat uppercase and lowercase letters as different on many servers, so lowercase paths avoid surprises. Underscores can hide inside link underlines, so hyphens read better in paths. Whatever style you pick for JSON, apply it to every field in every response.

Path Structure

/api/v1/customers/42/orders?status=paid&sort_by=date
 │   │      │      │    │        │
 │   │      │      │    │        └─ query parameters filter and sort
 │   │      │      │    └────────── child collection
 │   │      │      └─────────────── resource id
 │   │      └────────────────────── collection
 │   └───────────────────────────── version
 └───────────────────────────────── API prefix

Handling Actions That Are Not CRUD

Some operations do not map to create, read, update, or delete. Cancelling an order, sending an invoice, and resetting a password are actions. Model them as resources that represent the event.

POST /orders/7/cancellation
POST /invoices/31/deliveries
POST /users/9/password-resets

Each path names a noun that results from the action, which keeps the URL free of verbs.

Boolean and Date Fields

Name booleans like questions or states: isActive, hasDiscount, emailVerified. Name date fields with a suffix that describes the event: createdAt, updatedAt, expiresAt. Users understand a field without reading its description.

Avoid These Habits

• File extensions in URLs, such as /users.json.
• Trailing slashes that return a different result from the same path without one.
• Abbreviations that only your team knows, such as /cust or /ord.
• Database table names that leak internal design, such as /tbl_user_master.
• Different words for the same idea, such as id in one place and userId in another for the same field.

Writing a Naming Guide

A short written guide keeps a growing team consistent. List the rules for paths, fields, headers, and error codes. Add a table of approved words, such as always using "customer" and never "client" for the same concept. Review new endpoints against the guide before release.

Common Mistakes

Naming From the Database

Tables and columns reflect storage choices. Resource names should reflect what users understand.

Changing Names Later

Renaming a field breaks every client. Choose carefully the first time, and treat names as part of the contract.

Mixing Singular and Plural

A single endpoint that deviates from the pattern costs every developer extra time. Fix it before launch.