Best Practices for REST API Design

a live document

Expand below sections to read more about them

API Design


Combination of noun & verb.

Description Verb Noun API
Get all accounts Get Accounts GET
Delete a message with ID 1 Delete Meesage DELETE

Don't use verbs as part of the URLs.

HTTP verbs are there for this purpose only.

Status codes

Return proper status codes. Spend like 30 minutes to read all the status codes and their use case.


Let clients pass limit & page for all GET APIs.
Fallback to default values if they don't pass.



Read this. Also has info on multi-column sorting.

API Security

Rate limiting

Avoid DOS (Denial-of-Services) attacks.

Client exceeding limits should be sent following response status:

429 Too Many Requests

API management


Versioning keeps both API developers and consumers happy and loosely coupled.

Below is path based versioning // Version 1 // Version 2 // Version 3


At least, automatically generate swagger documentation using libraries and serve them using Swagger-UI.


If you think this is helpful 🎈
Don't keep it to yourself 🙊

Share it with your lovely followers at twitter 🗽

lets connect viatwitter