REST APIs, My Best Practices

Sooner or later, every developer needs to either use or implement a REST API. There are no strict standards on how a REST API should look like, so that’s why I’m sure you have seen many different ways of designing them.

So in order to make the developer’s life easy, that’s one of the reasons why you should stick as much as possible to the guidelines and best practices that are already in the market.

In this post I would like to share my experience after several years implementing and using REST APIs, going from big monolithic projects to microservices. Even though the problems that may arise when designing a REST API depends to a large degree on your specific domain, we can still run into some common issues that I would like to discuss.

Some of the most important points when designing a REST API are the following ones:

URL Mapping To Resources

Keep Your JSON Simple

Be Consistent In Your API

Paginate Collections

There are many more, but let’s discuss these firsts and, eventually, we could add more of them in the comments.

URL Resources

First of all, if you want to design a REST API, please check what the state of the art is. Follow as much as possible the conventions established. There are many websites available that can give you very valuable feedback (here one, another).

My advice here is to read those resource naming conventions, compare to what you already do and try to follow them as much as possible.

Keep Your JSON Simple

It’s better for everyone, easier to understand for humans and for developers (yes, they don’t belong to the same group).

A JSON is just a group of key pair values. When your domain is complex, you could use features like having different key-value pairs depending on a particular field value, or using IDs as keys, having complex structures inside other complex structures, returning many fields from several “resources” in the same response, etc.

Despite the fact that it can be very useful in some cases, I would recommend thinking it over before making those decisions.

There is nothing better for a client than exactly knowing the format that they’re going to receive, and to receive everything they need in one single endpoint. But in the end, we need to find a trade-off that allows us to have a flexible API and not a complex one. If not that will lead to several problems as our software evolves (as it should).

Be Consistent

Be consistent when you design the URLs to access your resources. Some examples are

• If you will allow PUT and PATCH for one specific resource, maybe it makes sense to allow it for more of them.
• If one resource can be queried, e.g. /api/customers?firstName=Manuel, it makes sense that other resources can be also queried
• If you allow partial responses for one resource, other resources should also have that feature.
• If your API has a new version, all the entities should move to the new version.

Humans (yes, coming back to the same joke), should be able to understand your URLs, and even get conclusions out of them. Conclusions like:

• Are there more content types supported?
• Is there any hierarchy in the resources?
• If I know more resources, can I guess their URLs?

To better illustrate this, let’s consider the developer twitter API as an example. Let us take this endpoint (source https://developer.twitter.com/en/docs/tweets/search/api-reference/get-search-tweets):

GET — “/1.1/search/tweets.json?q=from%3ANasa%20OR%20%23nasa”

If you look at the URL, what are you able to assume?

• Are there more content types supported? — It looks like, since we have tweets.json as part of the URL, I would also be able to request tweets.xml.
• If I know more resources, can I guess their URLs? — I would think I can also search for uses, /1.1/search/users.json…

This is just an small example to check how an URL can tell us much more than just the resource is pointing.

Paginate Collections

I’ve heard so many times things like, scenario 1:

• Paginator-Hater: We definitely don’t need pagination since this resource isn’t going to grow that much?
• Random-Developer: I think we should, but, I don’t have a strong opinion, so I guess we can live without pagination.

Or, scenario 2:

• Random-Developer: I think we should use pagination here.
• Paginator-Hater: No, we won’t, It isn’t a requirement.

And then, suddenly software evolves and you realize that not only pagination is needed, but also we need to release a new API version since we are going to introduce a backward incompatible change.

*The scenario 2 is based on a real story, at the end we had to add pagination (and yes, I was the Random-Developer).

Versioning

Versioning is a very controversial topic, basically the main benefit of using versioning is that it helps you to iterate faster.

The most used versioning approaches are these ones:

• MediaType versioning. Using Accept Media Type header
• Custom Header versioning. Using a custom header like Accept-Version.
• URI Versioning. The most used one, using different paths for different versions.

In this link you can find a detailed explanation of these and more approaches.

But there is another option that it’s getting more and more attention every day (specially in microservice architectures), which is to avoid versioning as much as you can. And, despite your possible first impression, this is the most difficult approach to handle “versioning”.

My two cents on this topic is to avoid versioning as much as possible. We all know that sometimes, it’s impossible to avoid breaking changes, so then versioning is a must.

Avoid versioning as much as possible

Developer’s first option is URI versioning, because it’s quite visual, so I personally recommend to use this approach, and to use this semantic vX (where X is the major release change), because, most probably you don’t need minor and bugfix granularity.

Having v before the release number, makes it clearer that that URI’s part is related to the version.

Contract and Documentation

Depending on the programming language you’re using there are many options available to document your REST API. But what’s important is that your clients are informed with the capabilities that your REST API provides.

They also need to be aware of the input/output format of your endpoints. If you use JSON, a good approach is to validate your JSONs with JSON Schema, schema that you can provide to your clients as a contract.

In general, before implementing an API, I recommend to follow this approach:

1. Developer comes with an API description.
2. That API description is reviewed by other developers and clients.
3. Developer implements the API.

In my experience, involving the clients in the design phase is a good practice, since it makes your API more robust, and helps to avoid misunderstandings that can lead to bigger problems in the future.

Involve the clients and other developers in the API implementation

In the above article I tried to share some of my best practices I have used in the past when working in the API design. My main idea is to save you time in the future, since maintaining an API can be difficult, specially when having several versions. I hope you all agree, and I am eager to hear about your experience in this topic.

Thank you for reading this article! If you enjoyed reading this story, clap for me by clicking the button below so other people can see this here on Medium.

I work at Sytac.io; We are a consulting company in the Netherlands, we employ around ~100 developers across the country at A-grade companies like KLM, ING, ABN-AMRO, TMG, Ahold Delhaize, and KPMG. Together with the community, we run DevJam check it out and subscribe if you want to read more stories like this one. Alternatively, look at our job offers if you are seeking a great job!

If you want to know more about me please check:

Github: manuelarte

Linkedin: manueldoncelmartos