How to choose the right API style and technology for your software architecture

Application programming interfaces (APIs) are an essential design element in any software architecture. They interconnect components digitally and allow various systems and devices to communicate easily with each other. When developers build a new API, they initially think about the API design and how the API interacts with the external world by selecting a style and technology.

This article explains the five most popular API styles. It looks at common questions like how to choose the right API style and which technology to choose for a style. It also provides practical scenarios where an API gateway like Apache APISIX can supplement an API's weaknesses.

[ For more on API gateways, read Use this open source API gateway to scale your API. ]

There's no "best" API style

Note that there is no single best way to approach all software design problems. The same is true with API styles. There is no "best" API style. They all have strengths and weaknesses that depend on the issue you're addressing.

The API styles I'll cover in this article are:

• Resource style
• Hypermedia style
• Query style
• Tunnel style
• Event-based style

I will go through each style and explain the main properties, interaction model, and limitations. Then I'll suggest 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, which 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.

[ Related reading: Generate OpenAPI documentation using AppMap ] 

Image

The "resource" in this context is similar in scope to what you would have in resources such as web pages when designing a website. The idea of resources gives you a great way to expose the relevant aspects of an API's functionality and, at the same time, allows you 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.

Representational state transfer (REST) is an architectural pattern for the resource style, but that doesn't mean that REST provides concrete technologies. For REST, HTTP is a preferred protocol. 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.

[ Related reading: An architect's guide to APIs: SOAP, REST, GraphQL, and gRPC ]

In developing REST APIs with many resource collections integrated with backend HTTP endpoints, you can use features in an API gateway such as Apache APISIX to help you with 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 synchronously. You can read more about how to choose the right API gateway for your REST APIs.

This resource style lacks 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.

[ Check out Red Hat's Portfolio Architecture Center for a wide variety of reference architectures you can use. ]

Hypermedia style

Just as on the web, you can navigate the most important paths across resources by using links between them instead of knowing each resource individually and entering its URI in the browser's address bar. The hypermedia style does the same but for an API's resources.

Image

On the web, humans read pages and then decide which link to follow. For hypermedia APIs, machines usually make this decision. This means links need machine-readable labels so that machines can identify the available options and 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 is often JSON. In a hypermedia API, you can "navigate" across resources using the links between them.

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

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

• They provide all the links necessary to choose the available resources in the next step.
• Links span resources, and it doesn't matter whether one or more APIs provide these resources.

All of this sounds very positive because the hypermedia style provides the necessary knowledge for API consumers to discover your API and what resources you offer them. You can build a hypermedia-driven REST service with any programming language and framework used in your stack.

However, the ease of browsing may increase the risk of the reader skipping through the materials and getting fragmented information. Also, since the client and server share data, it can lead to "chatty" APIs that require multiple interactions for the client to access all required information. What if API endpoints are exposed by several backend services (microservices and serverless APIs)? You can solve this by leveraging an API gateway with a response aggregator/composer functionality.

Moreover, API consumers do not know what they want from the beginning, and it is more efficient to write a query to get exactly what they want, as the query style offers.

[ Learn how IT modernization can help alleviate technical debt. ]

Query style

The query style differs 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 is similar to how databases work. They have an underlying data model for the data they store and a query language that can select and retrieve parts of that data.

Image

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

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

Although the query style has negligible disadvantages over its advantages, query complexity is one of them. 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 in resource style because REST APIs have multiple endpoints. They can leverage native HTTP caching to avoid refetching resources. Another problem with GraphQL is rate limiting, where you say "only this number of requests is allowed."

Nevertheless, the last two downsides (caching and rate limiting) can be addressed by introducing the API gateway between the client and data store. For example, an open source Apache APISIX API gateway can 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.

[ Create an organizational culture that fosters innovation. Download The IT executive's guide to building open teams. ]

Tunnel style

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

Image

A common technique used in this style is the Remote Procedure Call (RPC) 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. However, RPC APIs are much more difficult to maintain and update than REST APIs, so 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 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 expose procedures as APIs, where much of the task of "creating the API" can be automated. There still should be some management layer for securing the APIs. 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.

[ Use distributed, modular, and portable components to gain technical and business advantages. Download Event-driven architecture for a hybrid cloud blueprint ]

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. My article How to build event-driven APIs with webhook and API gateway explores this.

Image

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 centered around the delivery broker, and all event producers and consumers are connected to it. In this case, a good technology to consider is Apache Kafka, which 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 applied correctly, and error handling and troubleshooting can be challenging without adding third-party tools to monitor the event flow effectively. However, you can put an API gateway in front of event-driven APIs when observing modern applications with its simple built-in integration to several monitoring platforms.

Wrap up

These five styles are the foundation of popular approaches and technologies such as REST, OpenAPI, HTTP, gRPC, GraphQL, and Kafka. The key aspect of these five API styles is that there is no "best style." When choosing an API style, it all boils down to the following three classes: problem, consumers, and context.

• Problem: Each style has a certain focus and strengths. Thus, it is important to think about the problem the API addresses.
• Consumer: Every API is built for consumption. An API's consumers should always 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 you and your team are more familiar with and find easier to build might be a good fit for your project. Sometimes, you must use different styles together in one software project.

---

This article is adapted from the Apache APISIX blog and is republished with permission.