Dec 6, 20228 min read

How to choose the right API Style and Technology

APIs are an essential design element in any software architecture that interconnects components digitally and allows various systems and devices to communicate easily with each other. When we built a new API, initially we think about the API design, and how the API interacts with the external world by using which style and technology.

In this post, we’ll go through the 5 most popular API styles and look at very common questions like “How to decide on the right API style and which technology to choose for a style” and provide practical scenarios where an API Gateway can supplement their weaknesses.

No best API style

Note that there is no single best way of approaching all problems in a software design. The same is true with API styles. There is no “best” API style. They all have strengths and weaknesses that depend on the problem that is being addressed.

Let’s go through each style and understand the main properties, interaction model, and limitations.

Resource.
Hypermedia.
Query.
Tunnel.
Event-Based.

Then we pick a suitable style and technology that works well for the given style.

Resource style

The resource style as the name implies is resource-oriented. Many of today’s APIs use the resource style, and this can be easily verified by the popularity of OpenAPI, which is the most popular way of describing resource-oriented APIs. In this style, the main focus is on which resources to expose to consumers so that they can interact with these resources.

The resource in this context can be assumed to be similar in scope to what you would have in resources such as web pages when designing a website. The idea of resources gives us a great way to expose the relevant aspects of an API’s functionality and at the same time allows us to hide implementation details behind the resources. There can be resources for persistent concepts such as products, product categories, and customer information. Also, there can be resources for process-oriented concepts such as ordering products or selecting a shipping option.

For the resource style, there is REST as an architectural pattern, but that doesn’t mean that REST gives you concrete technologies. For REST, choosing HTTP as a protocol is a preferred choice, and for the representation format, it’s probably safe to say that JSON by far overshadows any other representation (such as the XML that was popular before JSON). When a client request is made through a RESTful API, it transfers a representation of the state of the resource to the endpoint.

In developing REST APIs with many collections of resources that are integrated with backend HTTP endpoints, you can use API Gateway features to help you with all aspects of the API lifecycle, from creation to monitoring your production APIs. API Gateway REST APIs use a request/response model where a client sends a request to a service and the service responds back synchronously. You can read more about how to choose the right API Gateway for your REST APIs.

Resource style lacks is the ability to better represent workflows across these resources. The hypermedia style adds a key component to the resource style to address resource-linking concerns.

Hypermedia Style

Just as on the web, the most important paths across resources can be navigated by simply using links between them (instead of having to know each resource individually and enter its URI in the browser’s address bar); the hypermedia style does the same but for the resources of an API.

On the web, humans read pages and then decide which link to follow. For hypermedia APIs, this decision is usually made by a machine. This means that links need to have machine-readable labels so that machines can identify the available options and then make a choice. These labels are conceptually similar to the text of a link that humans click on web pages, but the labels are represented in the machine-readable representation of resources, which nowadays in many cases will be JSON. In a hypermedia API, where you can “navigate” across resources using the links between them. Resource style sometimes requires HATEOAS.

HATEOAS is an abbreviation for Hypermedia As The Engine Of Application State. HATEOAS is the aspect of REST, which allows for dynamic resource routing.

There are two main advantages of hypermedia APIs over resource-style APIs:

They provide all the links necessary in the previous response to choose the available resources in the next step.
Links span resources, and it doesn’t matter whether these resources are provided by one API or several APIs.

All of this sounds very positive because the Hypermedia style provides the necessary knowledge for API consumers to discover your API themselves and what resources you offer to them. You can build a hypermedia-driven REST service with any programming language and framework used in your stack. For example, using ASP.NET Web API or Spring Boot Rest API.

However, the ease of browsing may increase the risk of the learner skipping through the materials and getting fragmented information. Also, since data is shared between client and server, it can also lead to “chatty” APIs that require a number of interactions for the client to access all required information, and what if API endpoints are exposed by multiple backend services (microservices and serverless APIs)?. The latter challenge can be solved by leveraging an API Gateway with a response aggregator/composer functionality.

Moreover, API consumers do not know what they want from the very beginning and it is more efficient to write a query to get exactly what they want as is offered by the query style in the next section.

Query Style

The query style is rather different from the resource and hypermedia styles because it provides a single entry point to access a potentially large set of resources. The idea of the query style is that these resources are managed in a structured form by the API provider. This structure can be queried, and the response contains the query results. At some level, this can be seen as similar to how databases work. They have an underlying data model for the data they store, and a query language that can be used to select and retrieve parts of that data.

One benefit of the query style is that each consumer can request exactly what they want. This means that with a well-constructed query, it may be possible to combine results that would have required numerous requests in resource/hypermedia APIs. For example, instead of sending several HTTP requests to different endpoints, you can POST a single “query” for all you need.

For the query style, it’s probably fair to say that GraphQL by now is by far the most popular choice when it comes to building single-page applications (SPAs). It is a language for querying databases from client-side applications. The big advantage that GraphQL has is that it plugs into a JSON-based ecosystem. While GraphQL does not use JSON for queries, it returns results in JSON which make it easy to process in JSON-focused environments.

Although query style has negligible disadvantages over its advantages, we can identify one of them is the query complexity. API consumers need to have a good understanding of the underlying data and query models (so that they know how to use the query API properly and make efficient requests to avoid recursion or getting too many nested resources). Also, it is more complicated to implement a simplified cache with GraphQL than implement it in resource style because REST APIs have multiple endpoints, they can leverage native HTTP caching to avoid re-fetching resources. Another problem with GraphQL is rate-limiting where you say we allow only this amount of requests.

Nevertheless, the last two mentioned downsides (caching and rate-limiting) can be developed by introducing the API Gateway between the client and data store to win in this situation. For example, an open-source Apache APISIX API Gateway has the matching ability to recognize GraphQL syntax. By efficiently matching GraphQL statements carried in requests, it can filter out abnormal traffic to further apply rate-limiting policies and improve system performance with its caching capability.

Tunnel Style

In tunnel style, an API is a collection of functions that can be invoked remotely. APIs become a simple extension of what is in a local programming scenario where all exposed procedures are available as APIs. The tunnel style is convenient for developers because it can take very little effort to create APIs.

A common technique used in this style is the Remote Procedure Call method. RPC is a request-response protocol, where a client sends a request to a remote server to execute a specific procedure, and then the client receives a response back. However, RPC APIs are much more difficult to maintain and update than REST APIs, so again RPC APIs aren’t used as much in modern API development.

gRPC is an efficient tunnel-style (RPC) implementation and is well-suited for distributed systems. It has SDKs for many languages and platforms, so it can be used widely, for communication across platforms and languages. gRPC is super fast and efficient because it uses Protocol Buffers (protobufs) to serialize and deserialize, the HTTP/2 standard for optimized binary transfers, and bidirectional streaming to avoid (long) polling and blocking HTTP calls.

Tools can be used to expose procedures as APIs, in which case a lot of the task of “creating the API” can be automated. There still should be some management layer for securing the APIs, but that can be addressed by using a component such as an API gateway and its gRPC proxying ability to convert payloads from one format to another over the same transport (from REST to gRPC or vice versa) if different API protocols are used in the system.

Event-Based Style

In the event-based style, the API provider creates events that are then delivered to consumers of the API instead of consumers requesting something from the provider. Consuming applications expect to be informed of any change of state on a specific record or records on API. There are many ways and technology options to consider when implementing an event-driven API. For example, we explored how to build Event-Driven APIs with Webhook and API Gateway in this post.

Another approach is that event consumers connect to a message broker that decouples them from event producers. The message broker takes care of managing events, and consumers must subscribe to certain event types so that the broker can make sure that events of this type are delivered to subscribers. In this case, the architecture is much more centered around the delivery broker, and all event producers and consumers are connected to this message broker. In this case, a good technology to consider can be Kafka which is Kafka is highly scalable and resilient.

Some drawbacks of choosing an event-based style are, it takes more time to implement compared to other styles, it may trigger multiple duplicate messages across different services if the style is not properly applied, error handling and troubleshooting can be challenging without installing & configuring third-party tools to monitor the event flow effectively. However, you can put the API Gateway in front of even-driven APIs when observing modern applications with its simple built-in integration to several monitoring platforms.

Wrapping Up

As we reviewed, 5 styles were the foundation of popular approaches and technologies such as REST, OpenAPI, HTTP, gRPC, GraphQL, and Kafka. The most important lesson to learn about these 5 API styles is that there is no “best style”. When it comes to choosing an API style, it all boils down to the following 3 classes: a problem, consumers, and context.

Problem – As discussed in the individual styles, each style has a certain focus and certain strengths. Thus, it is important to think about the problem that is addressed with an API.

Consumer – Every API is built for consumption, and thus an API’s consumers always should be an important design aspect. Since APIs ideally are reused, it’s not always possible to plan for all consumers and their constraints, but it makes sense to design with at least some consumers in mind and to make assumptions about others.

Context – Most APIs are part of an API landscape. That landscape can have a different audience and scope, depending on whether the API is meant for internal, partner, or public use.

Ultimately, the style that you and your team are more familiar with and easier to build might be a good fit for your project. Sometimes, we need to use different styles together in one software project.