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:

or also use a header in the request:

GET /user/1 HTTP/1.1
Accept: application/json
Version: 1

Tip 3: Use self explanatory endpoints

1: Use only plural nouns, never use verbs


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)


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



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Josep Mir

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