What kind of API style should you be using? From SOAP, to REST, GraphQL, and new styles like gRPC, there are many competing standards for designing APIs and the way consumers interact with them. We’ve written about each before, but as the industry changes rapidly, there are always new concerns and opportunities for comparison.

In a recent talk at our Austin Summit, James Higginbotham, an API/microservices expert and consultant at LaunchAny, gave an overview of popular API design styles. Since REST has been a de facto design standard for some time, James explored our current API design landscape to see if REST still deserves the champion title.

What it comes down to is less of a competition, and more of a study in how business objectives determine API style decisions. In this article, we’ll put “popularity contests” aside and consider API styles from the viewpoint of what’s best for API consumers. Especially with increased pressure on web API managers to productize APIs, many managers are seeking ways to create stunning developer experiences that not only attract developer users, but create long-lasting integrations.

APIs Solve A Variety of Use Cases

James Higginbotham of LaunchAny spoke at Nordic APIs in Austin in June, shedding light on API design concerns.

The first thing that James notes is that the functional breadth of APIs is wide — they really can be used to solve many different use cases. Since the customer experience, worker experience, and supplier/partner experience may be vastly different, naturally the appropriate API style may depend on the specific scenario.

Outside of API consumer differences, there are also many different interaction behaviors that affect functional implementation. James lists request/response, request/acknowledge, batch, publish/subscribe, and message streaming as interaction styles. Typically, he notes that APIs usually fall into the request/response category, and that other options cater to more nuanced circumstances.

Back in History: From CORBA to GraphQL

Another way to truly see the breadth of varying styles is to dig deeper into the history of web communication standards. James notes that in 1990s, the prevailing B2B API style was CORBA, a services description language. In James’ words, the goal of CORBA was to to “create interoperability between systems and even across programming languages by externalizing objects.”

SOAP was the next iteration. It was used for internal integration, and instead of objects treated things as services. There were many benefits of SOAP — it could work across a firewall, across multiple transport protocols, and also works with asynchronous callbacks.

The Power of the HTTP Protocol for APIs

However, with the rise of smartphones, web apps, and the IoT, the industry resorted back to HTTP. There’s a reason why HTTP has been a godsend for application-to-application communication and SaaS. Actually, there’s many reasons.

To cover a little of the basics, HTTP provides URLs that allow us to define resource paths. There are verbs (GET, POST, PUT, and PATCH) to enable acting on such resources, there are response codes, and there are headers that allow us to define client/server relationships.

Going a little farther, HTTP enables content negotiation. This allows APIs to negotiate what data formats (JSON, XML, can add CSV, etc.) or languages the API can support and send to a client. HTTP also enables caching, ETags, conditional requests, and concurrency control.

Why understand the ins and outs of HTTP? Well, though we’ve built a lot of support in HTTP to accomplish much functionality, James sees that:

“People are tunneling protocol semantics inside of HTTP, when they really could just use HTTP!”

In general, it’s important to understand the protocols we are using to transport data — as James notes, we often don’t think about these things when discussing design styles for APIs. With a better grasp of HTTP features, API practitioners could help boost API performance and robustness.

Comparing API Styles (Not A Smackdown)

As James says, the goal of any great developer or architect is thus:

“We look and understand contextually what is being offered, and then ask does that fit our specific use case — the context in which the consumers will be using?”

Therefore, let’s peek into each API style to see which kind of use case it fits into.

GraphQL

As we’ve covered before, GraphQL allows for a more expressive API. It enables consumers to select specific resources to query, increasing the robustness of a single API call. Though GraphQL standardized this style, James notes a similar query parameter interaction style was done at Linkedin in the past too.

GraphQL is a great fit for hierarchical data. Also, with field-level selection, strong typing, and introspection, GraphQL has many attributes that make it a solid fit for front-end APIs.

Some negatives include limited endpoint security enforcement, and limited Ops tooling. Also, because GraphQL uses POST, it’s like SOAP in that you can’t cache responses. The lack of cacheability and flexibility for content types could constrain an API; a reason against full adoption for some groups.

gRPC

Developed by Google Cloud, gRPC is an open-source RPC framework. With an IDL (Interface Description Language) similar to CORBA, gRPC uses a protobuf to run through generators to create a backend. James notes that gRPC is a good fit for deploying inside and organization, stating that a more public, client-facing network may be a little harder to scale if using gRPC.

For James, the downsides of gRPC have to do with its code generators, who you will have to become very friendly with. If you are working with many different programming languages, there may be some nuances among generators that you’ll have to learn. Like GraphQL, gRPC also comes with cacheability issues.

REST

When we talk about REST, we mean the constraints as described by Roy Fielding — the client server relationship, statelessness, cacheability, layering, code on demand, and having a uniform interface. James notes that CRUD, on the other hand, is a lifecycle pattern that is applied on top of REST — they are not one in the same.

A big advantage of using REST is the ability to layer and apply cache constraints. James describes how layering is important because it impacts the overall platform architecture. Most platforms require application servers on the backend, load balancers and reverse proxies on the front end, and the ability to push data to CDNs (Content Delivery Networks) on the edge. Working over HTTP enables this sort of communication between all intermediaries along the way. If you adhere to the HTTP specs, there’s a whole lot of advantage, and it can even increase API security.

James displays the many layers between the server and end client. As he says, there’s a lot to operationalize!

Hypermedia: The Links Matter

Recently on the blog we weighed the pros and cons of adopting hypermedia, and listed tools to aid that process. In his presentation, James added another reason to consider hypermedia, and it has to do with new communication systems.

As we’re seeing with ChatOps, APIs are now being used to insert tools into the conversation. As James puts it, “APIs are now meeting people where they need to get stuff done.” He’s primarily discussing how messaging channels like Slack are extending workflows into new environments. Now, people can make business critical decisions in their chat app of choice.

Hypermedia could help to customize content for these new environments while retaining UX across the board. By including unique URLs within a response package, hypermedia APIs can tell clients what capabilities are possible and in what scenarios. Hypermedia links could immediately reflect new user permissions, for example, without breaking changing on the client side. James sees hypermedia as a way for APIs to respond to next generation platforms and the new issues that may arise.

Webhooks & More

If you’re familiar with webhooks you’re probably familiar with Zapier and GitHub. The Github webhook informs users whenever a developer issues a new commit, revolutionizing the way software is produced but also opening a marketplace around CD/CI pipelines. Zapier has its own subscription-style REST Hook designed to reduce polling.

There are also Server-Sent Events, allowing us to stream events back to the client, message streaming, and more. For example, James mentions Kafka — a logged based storage solution that uses such communication styles to stream messages to interested parties inside of an organization.

Webhooks and similar styles seem fit for event-driven architectures — asynchronous environments where a particular action must trigger another action to occur.

So, Is REST Still A Relevant API Style?

In one word, YES. However, there is a lot to operationalize when it comes to API design — it’s more than the server and the client that is consuming the API. James reminds us to “think beyond the laptop,” and leaves us with 5 important takeaways:

1.  We must understand business problem first, and not privilege tech trends over business goals.
2. Become better educated on HTTP to decrease dependence on frameworks. Understand HTTP beyond that CRUD lifecycle, and don’t use something for which HTTP has already solved.
3. Evolve the frameworks you already use.
4. Think beyond the laptop: there is a lot more to operationalize in API design!
5. When comparing API styles, stop using “vs.” Rather, adopt “&” to see how each style may fit nuanced scenarios or complement each other nicely.

Sure, between GraphQL, gRPC, REST, and other API styles there are many ways to get something up and running quick. But, considering the management, scalability, and longevity of a service may influence the decision you make.

James reminds us that from a security vantage point, the more semantics involved, the more the more surface area exploits there are to cover! Lastly, and perhaps more important, the API style chosen must accommodate the developer persona you are catering your service to — your users are your guiding light!

For those of you early on in your API journey, good luck with your initial API style choice. API veterans — please leave your comments below on what you’ve learned to help others!