RESTful API Design: 13 Best Practices to Make Your Users Happy

First step to the RESTful way: make sure errors don't come back as 200 OK.

Architect at work. Daniel McCullough, unsplash.com

Web services have been around for as long as the HTTP protocol has existed. But especially since the advent of cloud computing, they have become a very common way of letting clients interact with our data.

I haven't been lucky enough to be a developer when SOAP APIs were still around. So I've mostly known REST, a resource-based architectural style for building APIs.

For a year or two already, I have been working on projects involving either building or using APIs.

Most of the APIs I've seen claimed to be "RESTful" — i.e. compliant with the principles and constraints of REST architecture.

Yet, some of them have been giving REST a very, very bad name.

Bad usage of status codes, plain text responses, inconsistent schemas… I've seen it all (or at least, a good bunch). So I've decided to write up what I think are some good practices when designing REST APIs.

#Disclaimer

I have no authority to say that the following practices comply 100% with the holy REST principles (if there is such a thing!). I gathered those from experience building and working with various APIs.

Likewise, I do not pretend to have mastered REST API design! It is a craft — the more you practice, the better you get.

I will expose some code snippets as "examples of bad design". If they look like something you'd write, it's okay! The only thing that matters is that we learn together. I hope this modest listicle will help us do just that.

Onwards: here are tips, advice and recommendations to design REST APIs that make your users happy.

#1. Learn the basics of HTTP applied to REST

If you're to build a well-designed REST API, you'd better know the basics of the HTTP protocol. I truly believe this will help you make better design decisions.

I find the Overview of HTTP on the MDN web docs to be a very good read for this. However, as far as REST API design is concerned, here's a TL;DR of HTTP applied to REST:

HTTP has verbs (or methods): GET, POST, PUT, PATCH and DELETE are the most common.
REST is resource-oriented and a resource is represented by an URI: /newspapers/.
An endpoint is the combination of a verb and an URI, e.g. GET: /articles/.
An endpoint can be interpreted as an action on a resource. For example, POST: /articles/ may mean "Create a new article".
At a high-level, verbs map to CRUD operations: GET means Read, POST means Create, PUT and PATCH mean Update, and DELETE means... well, Delete.
A response's status is specified by its status code: 1xx for information, 2xx for success, 3xx for redirection, 4xx for client errors and 5xx for server errors.

Of course you can use anything the HTTP protocol offers for REST API design, but these are basic things I believe you need to keep in mind.

#2. Don't return plain text

Although it is not imposed by the REST architectural style, most REST APIs use JSON as a data format.

However, it is not enough to return a body containing a JSON-formatted string. You need to specify the Content-Type header too! It must be set to the value application/json.

This is especially important for programmatic clients (for example, someone or a service interacting with your API via the requests library in Python) — some of them rely on this header to correctly decode the response.

Pro tip: you can verify a reponse's Content-Type very easily with Firefox. It has built-in pretty-display for responses with Content-Type: application/json.