API styles are a topic of much contention. Most API practitioners are familiar with the REST vs. GraphQL debate, but that’s not to mention the countless other styles out there. The good news is that there is a simple, objective process for narrowing down the best style (or styles) for your next API project. At the 2019 Platform Summit in Stockholm, expert API consultant Zdenek “Z” Nemec shared this process with us, analyzing the attributes of eight different API design styles.

The Playing Field

For his talk, Zdenek chose to compare and contrast eight of the most popular API design styles. Admittedly, he says, comparing these styles is like comparing “apples and oranges… and bananas,” in that some truly are architectural styles, while others are frameworks or protocols that heavily influence the nature of the API.

So, what styles are there to consider? Zdenek’s selection starts with the web APIs: REST and so-called REST. Then, there are the query APIs, mainly consisting of GraphQL. Next come the publish-subscribe APIs, including Kafka and WebSub. Finally, there are two RPC APIs — SOAP and gRPC — as well as plain old file transfer.

Constraints, Properties, and Considerations

Zdenek’s model for choosing API styles revolves around constraints, properties, and considerations. After all, an architectural style is really just “a set of constraints that — upon applying — give you a system with certain properties.” (We’ll leave the considerations aside for a second.)

Consider the following examples of this relationship between constraints and properties:

• An API that is decoupled (constraint) is inherently modifiable (property)
• An API that is stateless (constraint) is inherently reliable (property) and scalable (property)
• An API that implements a uniform interface (constraint) is inherently simple (property)

Of course, constraints can also result in negative properties. For example, poor efficiency is a property that might arise from the constraint of a uniform interface. However, to choose the right API style, Zdenek recommends you focus on what you do want (favorable properties), and not what you don’t want.

To pick which properties you want, look at the limitations of your organization in four different areas. This starts with business limitations, such as use cases, customer requirements, desired time to market, and your company strategy. Also consider domain limitations, such as government regulations or domain-specific issues. Then, look at cultural limitations, like style hype, practitioner knowledgeability, and support from others. Last but not least, review complexity limitations, including style difficulty, the need for scalability, and algorithmic complexity.

(Zdenek refers to these limitations as “product constraints,” but we’re referring to them as limitations to prevent confusion with the style-inherited constraints discussed earlier).

Based on your findings, you may aim to build an API with specific properties such as portability (the ability to be moved from one environment to another), visibility (the ability to analyze and manage internal traffic), and type-safety (the ability to recognize and reject incorrect data types).

Some of the more self-explanatory properties you might seek include:

• Performance
• Scalability
• Simplicity
• Modifiability
• Reliability
• Discoverability
• Ease of development
• Cost

Of lesser importance are the considerations we mentioned earlier. While properties directly impact the nature of your API, considerations are secondary, implementational issues related to the style at hand. They include:

• Maturity
• Enterprise readiness
• Tooling
• Community
• Style-specific resources
• Ease of externalization

Traits of Eight API Styles

The recipe for choosing the right API, says Zdenek, is simple: think about the properties you want to get (and the considerations that may affect your decision), and you’ll know which style to choose. Of course, to do so, you’ll need to know where the eight API styles in question stand in terms of constraints, properties, and considerations…

REST

Constraints: Client-server, stateless, cacheable, layered system, code-on-demand, uniform interface

Properties: Performance, simplicity, scalability, visibility, portability, discoverability, modifiability, reliability

Considerations: Maturity, enterprise readiness, community, ease of publication

Z’ Comments: REST is excellent for building a scalable system that lasts. It’s also a relatively flexible and mature style, so it’s good for things like content negotiation, multimedia, and top-of-the-line authentication.

So-called REST

Constraints: Client-server, stateless, cacheable, layered system, code-on-demand, uniform interface

Properties: Performance, simplicity, scalability, visibility, portability, discoverability, reliability

Considerations: Maturity, enterprise readiness, community, ease of publication, style-specific resources, tooling

Z’ Comments: So-called REST is what most API providers are doing since following the HTTP protocol gives you all of REST’s properties, bar uniform interface. Unfortunately, the absence of this constraint means that the so-called REST offers poor modifiability. Avoid using this style; instead, opt for REST or GraphQL.

GraphQL

Constraints: Client-server, stateless, layered system, uniform interface

Properties: Ease of development, costs, type safety

Considerations: Community, tooling

Z’ Comments: GraphQL offers incredible tooling and a great Developer Experience. It’s quick to set up and consume and works well for backend-frontend communication. However, it doesn’t evolve as well as REST.

Apache Kafka

Constraints: Client-server, stateless, uniform interface

Properties: Performance, visibility, scalability, discoverability, reliability, type safety

Considerations: Enterprise readiness

Z’ Comments: Kafka is a trending publish-subscribe style that’s fast, reliable, and scalable. While it has all the benefits of a message-based system — and stores messages permanently — it’s not great for externalization/publication, and requires plenty of Java prowess.

WebSub

Constraints: Client-server, stateless, cacheable, layered system, code on-demand, uniform interface

Properties: Simplicity, scalability, visibility, portability, discoverability, modifiability, reliability

Considerations: Maturity, enterprise readiness, ease of publication

Z’ Comments: WebSub is another publish-subscribe API style. Inheriting from REST, it works well even when externalized. It’s also language-agnostic. However, it’s certainly not as performant as Kafka.

SOAP

Constraints: Client-server, layered system

Properties: Visibility, discoverability

Considerations: Maturity, enterprise readiness, tooling, community, style-specific resources

Z’ Comments: It may not be the most modern style, but SOAP still has its uses. It lends itself well to building upon existing enterprise infrastructures (and cultures), especially for one-to-one integrations. For a longer-term strategy, however, be sure to consider other styles.

gRPC

Constraints: Client-server

Properties: Performance, simplicity, reliability, type-safe

Considerations: Maturity, enterprise readiness, community

Z’ Comments: gRPC is a bare-bones RPC framework backed by Google. While it offers excellent performance, it warrants reinventing much of what REST or GraphQL already provides. It’s not great for web applications or when a message broker would come in handy.

File Transfer

Constraints: Client-server

Properties: Ease of development, cost

Considerations: Maturity, enterprise readiness, tooling

Z’ Comments: It’s easy to overlook the humble file transfer. However, it’s a cheap and easy way to transfer data. It’s particularly useful for infrequent batch processing, where real-time capabilities aren’t needed.

Final Thoughts

Picking the most suitable design style for an API project is often a complicated process. Thankfully, Zdenek has a straightforward approach to finding the style that best meets your organization’s needs. He suggests you start by identifying essential properties for your API, before cross-referencing them against the constraint-induced properties of eight popular design styles. Zdenek also advises you to draw attention to any style-specific considerations that might sway your decision. And that’s all there is to it!