REST API Naming Conventions

By Archie To, 2025-10-02. Last updated 2025-10-30.

We’ve been building REST APIs for some of our projects. One of the struggles that I’ve personally faced was deciding on the URL structure for the endpoints. After some trials and errors and learning from others, here is a set of conventions that I think we should follow.

What is REST API?

In the simplest terms, REST API is the middleman between the client and the server. Clients make requests to REST API endpoints to either modify or retrieve data from the database or to trigger a specific action.

Think of REST API as a waiter in a restaurant. The client (customer) places an order (request) with the waiter (REST API), who then communicates with the kitchen (server) to prepare the food (data). Once the food is ready, the waiter brings it back to the customer.

REST-based API vs RESTful API

First, let’s clarify what REST is. REST (REpresentational State Transfer) is basically an architectural style of development having some principles:

  • Client/Server – Clients are separated from servers by a well-defined interface
  • Stateless – A specific client does not consume server storage when the client is “at rest”
  • Cache – Responses indicate their own cacheability
  • Uniform interface
  • Layered system – A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way
  • Code on demand (optional) – Servers are able to temporarily extend or customize the functionality of a client by transferring logic to the client that can be executed within a standard virtual machine

A REST-based API follows some of the principles listed above, while a RESTful (aka REST) API strictly follows all of them.

REST API Naming Conventions

This article uses ZooDB as an example. To summarize, the resources in ZooDB are organized as follows:

  • The database contains multiple Sites
  • Each Site contains multiple Excavations
  • Each Excavation contains multiple Samplings
  • Each Sampling contains multiple BoneCounts

Let’s talk about some conventions that we should follow when naming our REST API endpoints.

1. Resource-Oriented Naming

1.1. Use nouns to represent resources: URLs should describe the resource being acted upon, not the action itself. HTTP methods (GET, POST, PUT, DELETE) define the operation.

  • Good: /sites, /excavations, /samplings
  • Bad: /getSites, /createExcavation, /deleteSampling

1.2. Pluralize resource names: Always use plural nouns regardless of whether you’re dealing with a single item or multiple items.

  • Multiple: /sites, /excavations, /samplings
  • Single: /sites/{site_id}, /excavations/{excavation_id}, /samplings/{sampling_id}

2. Readability and Consistency

2.1. Use lowercase letters: URLs are case-sensitive, so using lowercase consistently prevents potential issues.

  • Good: /sites
  • Bad: /Sites, /SITES

2.2. Use hyphens (-) for word separation (kebab-case): Hyphens improve readability in multi-word resource names. Avoid underscores or camelCase in the URI path.

  • Good: /bone-counts
  • Bad: /bone_counts, /boneCounts

2.3. Avoid file extensions: Let the Content-Type header specify the data format.

  • Good: /sites/123
  • Bad: /sites/123.json

2.4. Use forward slashes (/) for hierarchy: Reflect the hierarchical relationships between resources.

  • Example: /sites/123/excavations (excavations belonging to site 123)

2.5. Avoid trailing slashes: Do not include a forward slash at the end of URIs.

  • Good: /sites/123
  • Bad: /sites/123/

3. Versioning

Include API versioning in the base URL: This ensures backward compatibility when introducing changes.

  • Example: /v1/sites, /v2/excavations

4. Query Parameters

Use query parameters for filtering, sorting, and searching: These parameters modify the retrieval of resources from a collection.

  • Example: /bone-counts?site=123&taxon=mammal&sort=count

5. Some examples

Get all sites:

GET /v1/sites

Get a specific site by ID:

GET /v1/sites/123

Get all excavations for a specific site:

GET /v1/sites/123/excavations

Create a new excavation:

POST /v1/excavations

Update a specific excavation:

PUT /v1/excavations/456

Delete an excavation:

DELETE /v1/excavations/456

Conclusion

Following these REST API naming conventions will help ensure that our APIs are intuitive, consistent, maintainable, and easy to use. This set of conventions can be carried out in multiple projects, making it easier for developers to build and consume APIs. However, there may be exceptions based on specific project requirements. If you need to deviate from these conventions, understand the reasons and document them clearly.

If you have any questions or suggestions, feel free to reach out!

References + Further Reading