Best Practices for REST API Design

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 🗽

lets connect viatwitter