a live document
Expand below sections to read more about them
API Design
Endpoints
Combination of noun & verb.
Description | Verb | Noun | API |
---|---|---|---|
Get all accounts | Get | Accounts | GET www.example.com/accounts |
Delete a message with ID 1 | Delete | Meesage | DELETE www.example.com/message/1 |
Don't use verbs as part of the URLs.
Eg: www.example.com/get-accounts
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.
Pagination
Let clients pass limit & page for all GET APIs.
Fallback to default values if they don't pass.
Eg: www.example.com/exployees?limit=100&page=2
Sorting
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
Versioning keeps both API developers and consumers happy and loosely coupled.
Below is path based versioning
www.example.com/v1/employees // Version 1
www.example.com/v2/employees // Version 2
www.example.com/v3/employees // Version 3
Documentation
At least, automatically generate swagger documentation using libraries and serve them using Swagger-UI.
Helpful?
If you think this is helpful 🎈
Don't keep it to yourself 🙊
Share it with your lovely followers at twitter 🗽