Pitfalls of REST API  -  What should we watch out?

5 min read time

All developer teams require the essentials such as consistent code quality, quick and efficient work, and a unified development environment. It’s no doubt that one of the most essential tool is the REST API system, which includes version control, structure of HTTP requests, method type and response appearance. A well-built API tells not only the proficiency of a developer, but it increases the development performance and long-term maintenance as well. Currently, there is no official guideline or standards for planning API’s. But before all we start, the goal of this article is not explaining the detailed precise realization, but rather describing the emerging pitfalls of each area. So let’s start…

What is REST?

REST (Representational State Transfer) is a type of software architecture, a loose coupling for huge internet based systems, such as the world wide web. A REST based architecture is made of clients and servers. The clients start requests towards the servers, the servers are processing the requests and sends back the appropriate respond. Originally, REST has been developed within HTTP, but it’s not limited to this protocol. A RESTful architecture can be built on other application protocol layers, if it has already a knowledgeable resource — representation transferable rich and unified vocabulary. The RESTful applications use the maximum out of the existing chosen network protocol’s well created interfaces and other built-in abilities. It also minimizes the introduction of the new application-specific features.

Why version control is needed?

It’s not a surprise that different versions do exists and each of them with different realization system schemes. One of the most popular is called the Semantic Versioning, which works based on the MAJOR.MINOR.PATCH changing principles. The MAJOR version changes, if backwards, there is no API compatible change. At this time, The MINOR and PATCH resets to zero. The numbering of the MAJOR, starts with 1 when it’s released at the first stabile live environment. The MINOR version changes, if functions were added backwards in a compatible way. The Patch version resets then to zero. The Patch version changes, when backwards compatible bug fixes are introduced. Further tags, as “developer” and “before release” will be supplemental for the MAJOR.MINOR.PATCH introduction.

API version control

There is no unified solution for API logical operation, and neither a standard for it’s versioning realization. It can be applied with versioned URL (there are more options here as well) or Request Header or Accept Header solutions. Of course each of them has advantages and disadvantages, but now we don’t dive into details, we can write whole independent articles of each. Let’s see what we need to pay attention rather:

We should bear in mind that the version number is not necessarily shows how much job was carried out. More precisely, if the Major version number shows the amount of the job done, then we did something wrong. The main version number should change exclusively, if the compared prior released version number needs such modifications such as, one or more prior requests or responds structure differs from the prior practice, or those client requests changes that demanded towards to REST API are indispensable. The quick sequential releases of MAJOR versions can be traced back to lack of planning or not appropriate planning. Thereto, maintenance and operations costs are increasing by each MAJOR version introduction:

A MAJOR’s version must be supported and available until it’s users rate reaches or approaches zero. (The decision making must be a unique business decision at all cases, which is influenced by the version’s operation cost, it’s user composition; or are there an individual contract for further support for a definite time given.)

All MAJOR versions must consist all supported requests, despites the version change is due to a sole incompatibility. In contrary, it would become untraceable for the client side and API developers, for which request can be find under which version number.

One of the pain point of version control is the documentation. It’s unavailing if the API gets better or “smarter”, if no one knows about it. That’s why, in case of each version change, a changelog needs to be published retroactively until PATCH level, that includes all realized changes compared to prior versions. Not to mention, that developers also lose trace sooner or later over what changed exactly, and how each request operates towards the API.

One more important thing: whichever version control we may decide, we have to make sure, how the API handles requests demands towards to non-existing versions or refers without a version.

HTTP requests (methods)

There are no standards regarding HTTP requests, rather just some guidelines exist. What is common, that all HTTP requests must identify the transacted operation unequivocally. We should look at the URL at one sentence, where the formula defines, what we are dealing with and the method states, how to work with it. In case of requests, safe and unsafe requests can be differentiated. These are concerned for the server’s status, more precisely those data that stored on the server. Safe requests are the type of requests, that used only for requesting information from the server, and can not change anything on the server’s status in theory. The following belongs to this: HEAD, GET,OPTIONS, and TRACE. It’s important to know that, the server side effects could differentiate in practice: such as it changes the last access date though. The formation of the request structure is another different topic; we don’t cover it now.

At all API requests, the clients must receive back the results of it’s sent out request or in case of failure what caused the problem. One of the indispensable tool for such requests, is the received status code by the server. It’s important to note, that the API can not understand all requests. In such cases, the REST API documentation should include the behavior of the servers, which runs the API. By understanding the requests, the API can have more type of return value, such as: item, list, system error message, or error message due to business logic. All API requests that perform listing should realize scrolling, sorting and filtering. However, there are more methodologies, each has it’s advantage and disadvantage as well. It’s logical realization depends on the environment, and the project itself, we don’t cover this topic now.


That’s true that currently, there are no official guidelines or standards for API planning and realization. But it’s quite visible, that popularity and spread of the internet, and computer program applicable tools has created several solutions for each specified environment or languages. The features of a good REST API are: accurate planning, precise development, and punctual documentation.

In so far as, we come to realize all three areas with the highest care, it can already decrease the problems on a short-term for developers and users. Furthermore, increases the demand regarding REST API, sustainability and last but not least the business profit.

Péter Pető
Author - Péter Pető

Inflex’s in-house, full-time resources are committed to the success of our clients. We work in small, empowered teams focused on delivering valuable mobile and web developments for clients every day.

More article