Yet another list of good practices for REST API design

REST API: A web service that can expose data or logic composed of a series of endpoints

Here there is my compilation of tips that helped me to design successful APIs to expose web services. This is nothing that I invented, I gathered all of them from different resources on the internet while I was working on it, so here is my humble contribution:

Tip 1: Document well your API

Tip 2: Version your API

There are different approaches to face this problem, one could be to add the version to the path just like:

yourdomain.com/api/v1/bikes
yourdomain.com/api/bikes?version=1

or also use a header in the request:

GET /user/1 HTTP/1.1
Host: myapplication.com
Accept: application/json
Version: 1

Tip 3: Use self explanatory endpoints

1: Use only plural nouns, never use verbs

/cars
/owners

2: Use accordingly http verbs to define actions

POST /cars        - to create new cars 
PUT /cars/32 - to update the data form car #32
DELETE /owners/4 - to remove the owner #4

3: Use subresources to access related data, but avoid going further than 3 levels

POST /parkings/556/cars - to add cars to the parking #556
GET /owners/43/cars - to get all the cars from owner #43

4: Provide filtering, sorting and pagination to the queries (when needed)

/cars?color=red&doors=3&fields=price,mileage&sort=-postedDate,+mileage&limit=10&offset=40

Tip 4: Be polite on your responses

Tip 5: Return meaningful errors

{
status: 400,
httpMessage: Bad Request,
apiStatusCode: 215,
message: Zip code format is not valid, it must be a 5 digit number,
description: Could not process the request.
}

Tip 6: Use stateless auth

Tip 7: Have you heard about HATEOAS?

HTTP/1.1 201 Created
...
Content-Length: 0
Location: /api/v1/cars/412
...

Tip 8: Use cache and set limits

Bronze tip: Prepare end-to-end tests

Silver tip: Monitor everything

Golden tip: Use common sense when designing

Software engineer as a profession, frustrated musician as a hobby, casual sportsman and social drinker in my free time. My personal blog: https://mirdevs.com