DEV Community

Best Practices for Naming API Endpoints

Sospeter Mong'are on September 02, 2024

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....

Read full post

Arvin Yorro • Sep 26 • Edited

/v1/orders/{id}/cancel

"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. ✅
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 • Oct 10

I see the pun at the end. haha!

Michael Slowik • Oct 11

I would suggest PATCH order with status = canceled instead

Sospeter Mong'are • Oct 12

Why, would you kindly provide the reason behind patch

Stanislau Shliakhtsich • Nov 7 • Edited

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

Rajat Soni • Oct 11

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 • Nov 15

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 • Oct 6

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

disturb16 • Oct 8

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 • Oct 10 • Edited

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 • Oct 10

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

Michael Slowik • Oct 11 • Edited

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.:

Rodgers Nyangweso • Nov 12

great stuff

Jude Ndubuisi 🥷🧑‍💻 • Oct 23

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 • Sep 28

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

Rodgers Nyangweso • Sep 4

awesome piece, kudos

Sospeter Mong'are • Sep 17

You are welcome

Jandrei • Oct 1

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.

Tiago Barbosa • Sep 30

This is a great post for anyone figuring their way out in building APIs. Straight to the point. Congrats!

Shubham Singh • Oct 3

informative