All APIs do not have to be Rest(ful)

Once again we visit our development team, which this time has to solve a pretty challenging problem. Because the ideas in the implementation of an API supported by Rest(ful) do not seem to work as desired. Unfortunately, consumers are not getting the data they need, but a lot of data that is not needed. For this reason, consumer feedback tends to be negative. But what went wrong here?
But first of all, let’s take a step back and get an identical understanding of the terms API and Rest(ful). Furthermore, I would like to discuss the contexts in which we are moving with regard to APIs.

What is an API anyway?

APIs represent mechanisms by which two software components communicate with each other via definitions and protocols. The term API stands for Application Programming Interface. The interface can be regarded as a service contract between the two components. This contract defines how the two communicate with each other via requests and responses.

What does rest(ful) actually mean?

REST is short for Representational State Transfer. REST is based on a set of functions such as GET, PUT, DELETE, etc. that allow clients to access server data. Clients and servers exchange this data using the HTTP protocol. The main feature of a REST API is statelessness. Being stateless means that servers do not store data from clients between requests. Client requests to the server are URLs similar to what is entered in a browser to display a website. The client then receives data structures in response.

In what particular contexts do we engage with APIs?

We very often use APIs in integration scenarios, where older systems, the so-called legacy systems, need to be linked to more modern software solutions through integration platforms and the use of residual APIs. The provision of digital products represents another opportunity for the use of APIs. Here, providers are no longer concerned with offering a direct product, for example in the form of an application, but only APIs bundled into a product to ensure access to the data. The terms API product and API as a product can be found in literature. The second term makes strong reference to product management thinking, whereas the first is only to be understood as a parenthesis.

Rest(ful) as solver of a problem

In the course of all the presented contexts, the use of Rest(ful) respectively the Resource style is generally felt to be a first general solution. But as I already noted in the first article of this series, it is very important to know the real use case of an API and also to understand it from the technical side.

Alternatives to Rest(ful)

If we now look at the technical side, we are moving in the area of tension of the so-called API Architecture. This term is intended to encompass all efforts with regard to architecture and technologies in relation to APIs. Thus, we are also simultaneously experiencing a new movement that is leaving the path of “one size fits all” solutions. In the following, I would now like to take a brief look at three other API styles apart from Rest(ful). These styles are also often referred to as API Interaction Patterns in the literature and thus represent the first level of a technology selection.

Tunnel

The idea of tunnel style goes back to the idea of Remote Procedure Call (RPC). From a developer’s point of view, this is a very convenient way to provide simple extensions for existing procedures for the purpose of exchange. But the handling around the tunnel, i.e. the technical access to the respective endpoint, made it difficult for the consumer to use. Which led to the availability of a simpler protocol for the “tunnel” with http and led to a proliferation of APIs based on the resource style.

Query

While with Rest or the Resource style we face one endpoint per resource, with the Query style it is only one endpoint where consumers are enabled to query the resources behind the API. The consumer now gets back exactly the result that matches their query. This in return means that there must be a good knowledge of both the data and the query models on the consumer side.
If we now look at the styles shown so far, we see that they are all based on the identical assumption. The consumer is the trigger of the interaction by sending a request and then waiting for a response. But what about when the consumer wants to be informed about every change and does not need to explicitly request.

Event-Based

Now the event-based style comes into play. With this interaction pattern, the publish/subscribe (PubSub) pattern also makes its way into the infrastructure. Based on events, consumers and producers can be directly connected or a message broker is located between the two for some decoupling. Unlike the other styles, we now find some sort of centralized architecture.

Conclusion

Back to the initial question. The team should look at the use case again in terms of the data model and examine it on the basis of the API interaction patterns mentioned. This should ensure that consumer feedback is a lot more positive. But this should not only meet the needs of the consumers. It is also a matter of making appropriate decisions with regard to one’s own architecture.