"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".
Backend Software Engineer passionate about web development, APIs, AI, and automation. I build scalable backend systems and digital solutions that solve real-world problems.
Location
Kenya
Education
BSC. Software Engineering
Pronouns
Mr
Work
Software Engineer | API Integration | AI & Automations | Technical writer | Mentor
Backend Software Engineer passionate about web development, APIs, AI, and automation. I build scalable backend systems and digital solutions that solve real-world problems.
Location
Kenya
Education
BSC. Software Engineering
Pronouns
Mr
Work
Software Engineer | API Integration | AI & Automations | Technical writer | Mentor
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?
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.
Backend Software Engineer passionate about web development, APIs, AI, and automation. I build scalable backend systems and digital solutions that solve real-world problems.
Location
Kenya
Education
BSC. Software Engineering
Pronouns
Mr
Work
Software Engineer | API Integration | AI & Automations | Technical writer | Mentor
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.
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)
I’m a software developer. I enjoy learning about technologies, as each offers a unique perspective to solving problems and challenges me. I find it rewarding to apply what I've learned.
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.
Full Stack Developer who is passionate about creating robust and scalable software solutions. Also a technical writer who excels at simplifying complex topics, making them understandable
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
Professional Data Engineer/Business Intelligence Developer. I build build and test various data pipelines between production and analytics databases. Additionally, I design dashboards.
Backend Software Engineer passionate about web development, APIs, AI, and automation. I build scalable backend systems and digital solutions that solve real-world problems.
Location
Kenya
Education
BSC. Software Engineering
Pronouns
Mr
Work
Software Engineer | API Integration | AI & Automations | Technical writer | Mentor
Professional Data Engineer/Business Intelligence Developer. I build build and test various data pipelines between production and analytics databases. Additionally, I design dashboards.
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".
I see the pun at the end. haha!
I would suggest PATCH order with status = canceled instead
Why, would you kindly provide the reason behind patch
PATH partially updates the resource; in this case, updating just the
order.statusmakes sense.In this context, the author gave an example of so-called Actions and not of the creation of cancelled orders.
Here they mentioned that for a single resource, we must use singular form.
Then
/users/{id}this should be/user/{id}, right?Exactly, I was also wondering about that.
POST /v1/users/{id}/posts/posts shouldn't be /post ?? You're creating only ONE post.Actually it is recommended to use plural, this allows you to also retrieve all posts for an user
GET /v1/users/{id}/postsFor 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/postsfor creating self posts.You are not creating but rather updating a resource based on the id of the resource
Hi i concern about approach of this problem:
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.:
This is a good read. I've learnt about naming conventions, resources grouping when forming an endpoint route,amongst others.
Nice read. I recommend.
Great read. However, does #5 & #6 in the first section contradict each other?
This is a great post for anyone figuring their way out in building APIs. Straight to the point. Congrats!
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.
Do you mind providing examples of what you meant?
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
awesome piece, kudos
You are welcome
great stuff
informative