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

REST:API

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

As long as you are building something that another person or persons will interact with, you should be very cautious about how you write the instructions to use it. Trust me, is better to write a proper documentation than use your email or phone as a help desk. There are some really cool tools out there to do so.

Tip 2: Version your API

The first time you break someone else’s application because you changed the behaviour of the api, maybe nothing happens. But the second time, that guy may look up where do you live or where do you work… To avoid these risks, version properly your api, in that way, functional changes in an endpoint can coexist in different versions. It is also a good practice to avoid weird endpoint names when you have changed your api and have two endpoints with the same functionality but different behaviour.

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

Definitely, not the easiest one, but there are some considerations to take into account of this point:

3.1: Use only plural nouns, never use verbs

/cars
/owners

3.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.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

3.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

Never return plain text and set properly the headers, that’s the minimum. Also for better understanding, use http status codes in all the responses. Likewise, it would say a lot about you if you are consistent in all your responses and use the same format across all the endpoints.

Tip 5: Return meaningful errors

Be polite in the error responses as well, don’t abandon your users in these difficult moments. Explain and detail what happened, and most importantly help users to recover from their own mistakes.

{
  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

The authentication and authorization in the API should be ensured within the request itself. It should not depend on any other previous requests. To achieve that you could use for instance JWT or OAuth2 or at least copy their behaviour.

Tip 7: Have you heard about HATEOAS?

To be honest, not a big fan. I don’t want to perform extra requests or receive extra stuff when I don’t needed it. But I would consider in alter requests (POST, PUT and PATCH) return a url link in the response of the resource impacted. For instance, the location header could be used for that purpose:

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

Tip 8: Use cache and set limits

You don’t want to suffer the consequences of the new loop function that one of your clients has just implemented and deployed in a larger and more powerful cloud infrastructure than yours. That’s just an example, but you have to deal and be prepared for the unexpected use of your api.

Bronze tip: Prepare end-to-end tests

Find the different use cases of your system and replicate all the steps and calls that a user may perform. Do not only analyze the response content, also check the performance, security, reliability,….

Silver tip: Monitor everything

Do not only measure the use of CPU or RAM on your servers, measure also the response times, the amount of requests of each endpoint, the time where these requests are performed, the database load,… All these tracking, together with the logs, will help you in the future to improve the performance of your api, and also to prevent and detect anomalies or even bug fixing.

Gold tip: Use common sense when designing

Don’t be disrespectful to other developers, imagine you are going to be the consumer of your own api. Would you not prepare it easy to use? The API is the UI of the developers, a good designer should provide an interface clear and as simple as possible, maintaining the stability and the consistency across all the services.


Thank you for reading all the way until here! If you want to comment this post you can do it on medium.com or dev.to.