We interview three experts on the state of REST API design

Representational State Transfer, or REST, is a dominant architectural pattern. Since Roy Fielding conceived it in 2000, REST has become the predominant method to design robust web APIs. However, with the advent of new application demands, some question whether REST is right for every single use case.

Alternative architectural styles and new tooling seem to bring into question: is REST still a good design style to use? To help answer that question, we interviewed three experts in the field: Thibault Ducret, Senior Backend Engineer at Delair, Henrik Stene, Technology Manager at Aboveit, and Zdenek “Z” Nemec, Founder of Good API Consulting.

Is REST still a good design style to use?

In short, all panelists agree that REST is still a relevant and useful style. One reason is that REST was designed to last.

“If you are building an API product that will be consumed by clients you have no control of, it should scale indefinitely and last for decades,” said Z. “For that, there is no better style but REST.”

Due to its popularity, many developers are already comfortable with REST. There are ample REST client libraries in most programming languages. As Thibault notes, “developers need minimal information to use a RESTful API in their application.”

All panelists agree REST brings usability benefits and is a quality foundation for API design. However, all recognize that individual application requirements may necessitate other technologies. As Thibault notes, “[easy] adoption is not the only criterion to choose your API design.”
“We must consider the needs and requirements for each application or endpoint on a case-by-case basis,” said Henrik. “I believe that REST APIs can provide a great starting point for most APIs, but there exist some good reasons to supplement REST with other technologies as well.”

For Z, the question of whether or not to use REST comes down to the nature of the product. “I see API styles like REST, streaming, or query as a function of the API’s product-market fit,” said Z.

Thibault adds that REST is often misinterpreted. Nearly all “RESTful” APIs lack a key component: hypermedia. So, technically, we never entered the REST paradigm because most APIs aren’t even REST at all.

For what use cases is REST not a good fit?

REST is applicable for many use cases, but it does leave gaps. As Henrik puts it, “I don’t really believe that REST is not a good fit for any of the traditional use cases, but there are other technologies that will help to ‘supercharge’ APIs and make them better.”

Thibault notices three distinct areas where REST is not a good fit: messaging, internal microservices, and performance with GraphQL and gRPC.

As Thibault describes, messaging-style APIs aren’t a good fit for REST because they force users to do constant polling; a headache and a performance drain. “You would rather design architecture around the Publish-subscribe pattern and implement it through the web socket protocol,” said Thibault. Likewise, Z argues that REST isn’t applicable for event-driven or push APIs.

Another instance where REST is insufficient is when you break apart a monolith and have microservices that must communicate with each other. In this scenario, “you may be tempted to replace function calls of the monolithic application with synchronous REST API requests,” said Thibault. This creates a series of sequential API requests, essentially perpetuating the monolith.

Z also recognizes that dogfooded internal services may benefit from alternative API design styles. “One of the use cases where you might use another API style is if you are talking to yourself,” said Z. “That is, if you are building a Backend for Frontend, you are the only user of that API, and you can coordinate the deployments of both components.”

Lastly, Thibault believes REST does not cater well to scenarios where high performance is critical for users. In REST, developers are unable to call multiple resources with a single API call or retrieve only the properties the client requires. For these scenarios, Thibault recognizes that GraphQL is a more elegant option. Alternatively, there are other options, such as adding a fields query parameter or using an optimized (but less readable) payload like gRPC.

Taking API design beyond REST

So, knowing the drawbacks of REST, is it inevitable that other design styles will supersede it? The answer is not cut and dry.

Henrik acknowledges every case is unique. However, he does see a clear trend. “We have all observed a shift in the industry in regards to how data is stored and shared,” said Henrik. “This change allows other technologies to shine.”

Thibault describes how usability was a significant factor for stepping out of the REST architecture style at his company, Delair. “Many operations were using the same endpoint in spite of being different,” said Thibault.

To increase usability, Delair replaced this single generic endpoint ’/dataset` (PATCH) with specific endpoints:

• /rename-dataset (POST)
• /add-dataset-categories (POST)
• /update-dataset-ingestion (POST)
• /update-dataset-horizontal-srs (POST)
• and more.

“This API is much more readable for the user and allows a simpler implementation for our backend, said Thibault.

Technical styles are simply guidelines and don’t always reflect the best way to generate value. API design choices come down to a matter of knowing what’s best for the team, developer consumer.

“When you have to twist your API to match the REST paradigm, it may be a clue that you could find another way to design it,” said Thibault.
“REST is just a tool,” reiterated Z. “The designers should first focus on the design and communication of their domain models and actions and only then on the nuances of a particular API style.”

Are asynchronous environments disrupting the typical REST expectation?

As we’ve covered before, new asynchronous streaming-style APIs are emerging. These event-driven services involve alternative protocols and even have new communities and standards such as Async API. But does this affect REST design?

Henrik notes their emergence and potential for evolving the current REST norm. “Asynchronous APIs is becoming more popular due to API consumers having different expectation of availability of data than they had before,” said Henrik.

Thibault also sees a scalability issue for asynchronous if stuck in a REST paradigm:

“When you need to provide event notification for several services, REST reaches its limit (as well as all the synchronous HTTP APIs). Notifying a service at the end of a process can be done with a callback, but what about notifying ten services? How long will it take if all these callbacks are executed sequentially? What happens if a new service needs to receive the notification too? Using REST and callbacks is clearly not scalable for this purpose.”

Thibault describes how Delair uses an Apache Kafka cluster for a message broker. This enables services to subscribe to a message queue to process requests asynchronously.

According to Z, asynchronous requirements can complement a REST offering, rather than disrupt it. In terms of tooling, in addition to Kafka, he highlights WebSub as a viable option.

“The WebSub is an amazing protocol that is efficient, fixes the problems with webhooks and plays nicely with REST and hypermedia and as such it seamlessly adds the “push” functionality to REST APIs,” said Z. “As such, it seamlessly adds the “push” functionality to REST APIs.”

Major takeaways

Well, there you have it. The state of REST API design according to some of the industry’s brightest thinkers. To summarize:

• REST is still relevant. REST is still a good style to use for most applications. It has an active tooling community, and developers are generally comfortable with it.
• However, REST has shortcomings. REST does not provide flexible data retrieval patterns like GraphQL. REST does not scale well with high-volume event-driven scenarios.
• Other options exist. For example, GraphQL or gRPC. Kafka or WebSub can add push functionality to REST APIs. Internal microservices or Backend for Front ends may benefit from alternative API styles or message brokers.
• Business comes first. Do not let style dictate too much. Build your technology to match your ideal communication and business models, not the other way around.
• Developer Experience (DX) is style agnostic. Quality developer experience can be accomplished using a wide variety of API styles.

Explore API design styles from the Platform Summit

For deeper insights, explore each panelist’s talk from the 2019 Platform Summit:

• Attend Henrik Stene’s session Creating APIs Beyond REST. This is an “experience talk” where I will try to explain how we ended up with the combinations of APIs that we did at Entur (the customer), and what we had to consider before implementing the APIs.
• Attend Thibault Ducret’s session We are not RESTful anymore… and it’s fine
  I will present the issues we had at Delair when building our RESTful APIs. I will walk you through real-world examples (involving drones!) and detail the ways we got around the problems. You will get a good overview of our API style, and the benefits since the implementation.
• Attend Zdenek “Z” Nemec’s session What API: Your Guide to API Styles. First, I hope to explain this product-driven approach to the selection of the API style. We as engineers tend to see everything as nails once we have the hammer in the form a certain API style. With this knowledge, I’d like to provide a framework for making decisions on what API style to use for a given product.