RESTful API Design: 13 Best Practices to Make Your Users Happy

[utterances-bot]

RESTful API Design: 13 Best Practices to Make Your Users Happy

First step to the RESTful way: make sure errors don't come back as 200 OK.

https://florimond.dev/blog/articles/2018/08/restful-api-design-13-best-practices-to-make-your-users-happy/

[iancrrn]

Great article! Thanks.

[sparkeplug]

Straight to the point 👍👍👍

[syeikhanugrah]

Nice article! what about sorting? thanks.

[eLPe21]

@syeikhanugrah
api/articles?sort=+author,-publishedDay
-publishedDay means Descending
+author means ascending , + can be omitted.
When looking into your question seen an example to use * to prefix calculated fields.
https://jsonapi.org/format/#fetching-sorting

[mokapoka]

Thank you for your effort, the article very clear and have great examples for easy understanding.

[kymotz]

👍👍👍, learned this article.

[ghost]

NIce and easy explanation

[itsshubhamm12]

Nice one, very informative and well structured!!

[milkcoke]

This is the best article I've seen REST API design guide. So simple and straightforward.

[OKT92]

I agree with not to use verb in URI. But what is the proper way to deal with the case below?

A user sign up a new account and submit related document for identity verification.

Endpoint for admin:
GET: /users ---> get all users
POST: /users ---> create new user
GET: /users/12345 ---> get user info
PATCH: /users/12345 ---> edit user info (name, contact, address...)

We may have more than one action on a resource. Example:

1. Admin help to reset password for user "12345"
2. Admin change the isVerified = true after review their submitted document.

My ideas as below but they seem like not proper.

1. PATCH: /users/12345/reset-password
2. PATCH: /users/12345/verify-identity

Any thought?

[milkcoke]

@OKT92

Yes, these are not proper.

1. PATCH: /users/12345/reset-password
2. PATCH: /users/12345/verify-identity

I suggest an example.

Edit user's partial information example

Request: [PATH] /users/12345

1. user authentication logic is executed
2. accept like below request body

{
  "new_password": "~~~~"
  "new_address": "~~~"
} 

3. Reflect update

Response

204 No Content
There's no response body

Conclusion

Recommend that use API URI without verb, nested path (You can specify entity id, in this example 12345) and also use response 204 No Content when PATCH request is done successfully

Refer this document