Yet another list of good practices for REST API design

Tip 1: Document well your API

Tip 2: Version your API

yourdomain.com/api/v1/bikes
yourdomain.com/api/bikes?version=1
GET /user/1 HTTP/1.1
Host: myapplication.com
Accept: application/json
Version: 1

Tip 3: Use self explanatory endpoints

/cars
/owners
POST /cars        - to create new cars 
PUT /cars/32 - to update the data form car #32
DELETE /owners/4 - to remove the owner #4
POST /parkings/556/cars - to add cars to the parking #556
GET /owners/43/cars - to get all the cars from owner #43
/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

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Real code: Spring boot with OpenFeign client, Hystrix and Spring Service Locator pattern — Part 1

Up and running: Phoenix 1.3 / Webpack 3

CouchDB authorization in a database

Update Your Updates

Article on GIT and GITHUB

Tableau & Snowflake: SQL UDFs and Workdays Example

Coding log: Importing Go Private Repository Module

Install Collabora Online with Docker on Ubuntu in ZenTao

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

Josep Mir

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

More from Medium

Factory Method Pattern vs Simple Factory

SOLID Principles for Maintainable Code

What is Microservices Architecture?

Exploring Design Patterns — Composite Pattern (Basic Arithmetic Expression)