Best Practices for Naming API Endpoints

When naming your #API endpoint requests, it's important to follow best practices to ensure that your API is intuitive, consistent, and easy to use. Here are some guidelines and examples to help you name your API endpoints effectively:

1. Use Nouns for Resource Names. Endpoints should represent resources (nouns) rather than actions (verbs). For example, use /users instead of /getUsers.

2. Use Plural Names for Collections. When referring to a collection of resources, use plural nouns (e.g., /users). For a single resource, use the singular form along with its identifier (e.g., /users/{id}).

3. Use HTTP Methods to Define Actions.

   • GET. Retrieve a resource or a collection of resources (e.g., GET /users, GET /users/{id}).
   • POST. Create a new resource (e.g., POST /users).
   • PUT or PATCH. Update an existing resource (e.g., PUT /users/{id} or PATCH /users/{id}).
   • DELETE. Remove a resource (e.g., DELETE /users/{id}).

4. Hierarchical Structure. Use a clear and logical hierarchy to represent relationships between resources (e.g., /users/{id}/posts to represent posts by a specific user).

5. Use Consistent Naming Conventions. Stick to a consistent naming convention, such as snake_case or kebab-case, and be consistent throughout your API (e.g., /user_profiles or /user-profiles).

6. Avoid Special Characters and Spaces. Use hyphens (-) to separate words instead of spaces or underscores in URL paths (e.g., /user-profiles rather than /user_profiles).

7. Keep It Simple and Intuitive. Names should be easy to understand and remember. Avoid complex or overly technical terminology.

8. Version Your API. Include versioning in your endpoint paths to allow for future changes without breaking existing clients (e.g., /v1/users).

9. Describe Actions with Query Parameters. Instead of using verbs in your endpoint paths, use query parameters for filtering, sorting, or searching (e.g., GET /users?status=active).

Examples of Well-Named API Endpoints

Here are some examples of well-structured API endpoints following these best practices:

1. User Management.

   • GET /v1/users – Retrieve a list of users.
   • GET /v1/users/{id} – Retrieve a specific user by ID.
   • POST /v1/users – Create a new user.
   • PUT /v1/users/{id} – Update a user's information.
   • DELETE /v1/users/{id} – Delete a user.

2. Authentication.

   • POST /v1/auth/login – User login.
   • POST /v1/auth/register – User registration.
   • POST /v1/auth/logout – User logout.

3. Resource Relationships.

   • GET /v1/users/{id}/posts – Retrieve posts created by a specific user.
   • POST /v1/users/{id}/posts – Create a new post for a specific user.

4. Pagination and Filtering.

   • GET /v1/users?page=2&limit=10 – Paginate users with 10 per page.
   • GET /v1/posts?sort=desc&category=tech – Retrieve posts sorted by date in descending order and filtered by category.

5. Complex Operations with Clear Naming.

   • POST /v1/orders/{id}/cancel – Cancel an order.
   • PUT /v1/users/{id}/password – Update a user's password.

6. Error Handling and Statuses.

   • GET /v1/orders?status=pending – Retrieve orders with a pending status.

Conclusion

You can create a clear, consistent, and easy-to-use API that developers will find intuitive and efficient when you follow this practices. Naming conventions are crucial in API design as they provide clarity and reduce confusion, making it easier for developers to understand and interact with your API.

Comments

[Arvin Yorro]

/v1/orders/{id}/cancel

1. "Cancel" is a verb ❌ - Change it to a word that best describes the state of the resource post-operation. Suggestions: "Cancelled" if the status is Cancelled or "Cancellation" if you prefer an actual noun. ✅
2. POST is meant for creation of resource ❌ Use PATCH for partial updates ✅

The rest are fine (no pun intended) 👍

I think REST is good practice but calling it the "best practice" makes it dogmatic and it turns away people. REST is just one way to get the job done. So lets call it "REST practices".

[Sospeter Mong'are]

I see the pun at the end. haha!

[Michael Slowik]

I would suggest PATCH order with status = canceled instead

[Sospeter Mong'are]

Why, would you kindly provide the reason behind patch

[Stanislau Shliakhtsich]

In this context, the author gave an example of so-called Actions and not of the creation of cancelled orders.

[Rajat Soni]

Use Plural Names for Collections. When referring to a collection of resources, use plural nouns (e.g., /users). For a single resource, use the singular form along with its identifier (e.g., /users/{id}).

Here they mentioned that for a single resource, we must use singular form.
Then /users/{id} this should be /user/{id}, right?

[Dang Ngoc Phu]

Hi i concern about approach of this problem:

• Suppose I want to write an endpoint to get /users?status...&... to get users information to view the overview users.
• In other usecase, I want to get the list of users with different query param, with more fields, so should I use the same endpoint and data model response.

[Fagner Araujo]

POST /v1/users/{id}/posts /posts shouldn't be /post ?? You're creating only ONE post.

[disturb16]

Actually it is recommended to use plural, this allows you to also retrieve all posts for an user GET /v1/users/{id}/posts

[Carmen Santiago]

For me the endpoint part "/users/{id}" is an authorization problem. Should not this information be taken from authorization? Im not allowed to create posts for any user id I want

It should be just POST /v1/posts for creating self posts.

[Sospeter Mong'are]

You are not creating but rather updating a resource based on the id of the resource

[Michael Slowik]

In ref to point 4:

Sort should include column name and "-" for descending, for example sort=-id (by id descending). In advanced use cases you can include multiple parameters like sort=-views,created_at

It would be a good idea to wrap query in filters (filter[user_id]=3) and support operators for example (filter[created_at][>]=2020-01-01)

Ref.:

• jsonapi.org/format/#fetching-sorting
• jsonapi.org/format/#query-paramete...

[Rodgers Nyangweso]

great stuff

[Jude Ndubuisi 🥷🧑‍💻]

This is a nice write-up, glad I am already following most of this practice. shows I am in the right direction also learned new things as well and why I shouldn't do others

[Chandra Panta Chhetri]

Great read. However, does #5 & #6 in the first section contradict each other?

[Rodgers Nyangweso]

awesome piece, kudos

[Sospeter Mong'are]

You are welcome

[Jandrei]

Also a good practice is to add version, domain, feature, function and operation to the path. Everything you post is good and must be used, in big companies you need more detailed info in the path.