It’s very unlikely that there’s anyone in the API space who isn’t at least tangentially aware of REST, the principles set by Roy Fielding in 2000 that inspired the standard of modern API design. Yet, while most people are familiar with terms like REST, REST-like, and RESTful, the difference between them might not be immediately apparent.

The short version of this is that REST is an architectural style, and REST APIs are web services that implement it. However, to complicate matters, developers call an HTTP web API using a CRUD style that’s mostly (but not 100%) REST a RESTful service.

In other words, it’s not quite as simple as “REST is the noun and RESTful is the adjective.”

So, can the terms be used interchangeably? For the most part. But that doesn’t mean that they should be. Below we’ll be taking a closer look at the origins, and the recommended usage, of REST and RESTful. We’ll also elaborate on the subtle differences between REST terminology.

Define: REST (and History)

Let’s start with the basics. REST stands for REpresentational State Transfer and is an architectural style comprised of various principles:

• Stateless: REST applications must be stateless.
• Client-Server (Separation): Independent modification of these components is essential.
• Layered System: Components of REST systems must not be able to see beyond their layer.
• Cacheable: REST server data must be marked as cacheable or not.
• Uniform Interface: There is an emphasis on a uniform interface between components.

Outlined in Roy Fielding’s dissertation in 2000, it took a while for REST to be dubbed the “SOAP killer” that it later came to be seen as. Designed to be easier to use and more flexible than SOAP, early adoption by eBay and Amazon spoke to the bright future of REST.

In the years to come, REST would become a dominant architectural style in the API space. If you’re developing an API in 2021, with very few exceptions, a thorough understanding of REST API design is one of the more essential tools you’ll want to have at your disposal.

Although plenty of API best practices like…

• Accesses resources from server using URI
• Uses HTTP protocol only (and verbs like GET, POST, PUT and DELETE for CRUD operations)
• Returns results in the form of JSON or XML, atom, OData, etc.

…exist and are associated with REST, not all of it has been explicitly defined by Fielding. In fact, much of what makes up REST has always been fairly loosely defined.

In reference to the “Uniform Interface” constraint mentioned above, however, HATEOAS (Hypermedia as the Engine of Application State) is a key constraint of REST application architecture. However, it’s also one that many developers don’t think is necessary… thus leading to the RESTful result.

Define: RESTful (& REST-based, REST-ish)

As already mentioned above, an API that’s described as RESTful adopts and adheres to the tenets of REST architecture. What it might not do, however, is conform to the constraints of HATEOAS — Roy Fielding argued in 2008 that REST APIs must be hypertext-driven.

You might see some providers proclaiming their services to be REST-based or REST-ish. This is usually shorthand for following some, but not all, of the principles outlined by REST. As we’ve seen above, RESTful is more likely to be used to describe services that follow all, or almost all, of the principles of REST.

Incidentally, there are various reasons why a service might need to deviate from having a REST architecture, so there’s no need to discard REST-based as inferior or invalid. It is, however, worth looking at which principles it does/doesn’t follow and how that might affect implementation.

As early as 2017, 83% of public APIs were “REST APIs” compared with 15% that were SOAP APIs. But perhaps the use of that term in this context is misleading. Because REST refers to architectural constraints, and is language and platform agnostic, there’s no simple and straightforward picture of what a “REST API” should look like. Numbers like those above likely encompass RESTful and REST-ish/REST-based services as well.

Even so, there’s no denying that REST API development has achieved (and maintains) dominance in the space. It’s also clear to see that its main opposition is no longer SOAP, but the newer and sleeker GraphQL.

The Future of REST/RESTful

In 2020, we observed that 82% of APIs were RESTful (OpenAPI/Swagger) and 21% were RESTful (not OpenAPI/Swagger), while 19% used GraphQL. It’s worth noting that GraphQL isn’t a direct “competitor” of REST since it’s a language rather than an architectural style. Despite that, it has been touted by some as an alternative to REST APIs since its introduction by Facebook.

There’s a plethora of “REST in Peace” articles, which is good wordplay to be fair, out there. Many of them suggest, or stop just short of suggesting, that GraphQL will render REST irrelevant.

Well, we’re now in 2021, and that still hasn’t happened.

According to the numbers cited above, the use of REST architecture in public APIs has only dropped by a percentage point or so. That isn’t surprising, given that overhauling an API requires an enormous amount of development and isn’t something to be undertaken lightly.

Whether or not GraphQL, or some other exciting new approach to API development, will unseat RESTful development in the years to come remains to be seen. For now, however, REST remains supreme, so there’s no need to tear down all of your RESTful APIs just yet!