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.

  • Use hyphens to separate words
    Eg: www.therdnotes.com/rest-api-design-best-practices

Query parameters

  • Use underscore to separate words
    Eg:
    www.therdnotes.com/posts?sort_by=id

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.


Sources:

Helpful?

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

Share it with your lovely followers at twitter 🗽

lets connect viatwitter