It is very unlikely that there is anyone in the API space who is not at least tangentially aware of REST, the principles established by Roy Fielding in 2000 that inspired the modern API design standard. However, although most people are familiar with terms such as REST, REST-like and RESTful, the difference between them may 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 is primarily (but not 100%) REST a RESTful service.
In other words, it is not as simple as «REST is the noun and RESTful is the adjective».
So can the terms be used interchangeably? In the majority of cases. But that doesn’t mean it should be. Next, we will look more closely at the origins and recommended use of REST and RESTful. We will also delve into the subtle differences between REST terminology.
Defined: REST (and History)
Let’s start with the basics. REST stands for Representational State Transfer and is an architectural style composed of several principles:
- Stateless – REST applications must be stateless.
- Client-server (separation): independent modification of these components is essential.
- Layered system: REST system components must not be able to see beyond their layer.
- Cacheable – REST server data must be cached or not.
- Uniform interface – Emphasis is placed on a uniform interface between components.
Described in Roy Fielding’s dissertation in 2000, it took some time for REST to be called the «soap killer» who later came to be seen. Designed to be easier to use and more flexible than SOAP, the early adoption by eBay and Amazon spoke of the bright future of REST.
Over the next few years, REST will become a dominant architectural style in the API space. If you are developing an API in 2021, with very few exceptions, a deep understanding of the REST API design is one of the most essential tools you want to have at your disposal.
Although there are many good API practices such as …
- Access server resources using URIs
- Use only the HTTP protocol (and verbs like GET, POST, PUT, and DELETE for CRUD operations)
- Returns results as JSON or XML, atom, OData, etc.
They exist and are associated with REST, not everything has been explicitly defined by Fielding. In fact, much of what makes up REST has always been defined rather vaguely.
However, referring to the “Uniform Interface” constraint mentioned above, HATEOAS (Hypermedia as the application state engine) is a key constraint of the REST application architecture. However, it is also one that many developers do not consider necessary … leading to the result of RESTful.
Define: RESTful (and based on REST, REST-ish)
As already mentioned above, an API described as RESTful adopts and adheres to the principles of REST architecture. What it may not do, however, is in line with HATEOAS limitations: Roy Fielding argued in 2008 that REST APIs should be based on hypertext.
You may see that some providers claim that their services are REST-based or REST-based. This is usually an abbreviation to follow some, but not all, of the principles outlined by REST. As we have seen before, RESTful is more likely to be used to describe services that comply with all or almost all of the REST principles.
By the way, there are several reasons why a service might need to deviate from having a REST architecture, so there is no need to reject the REST-based one as inferior or invalid. However, it’s worth looking at the principles you follow or don’t follow and how they might affect your implementation.
As of 2017, 83% of public APIs were “REST APIs”, compared to 15% which were SOAP APIs. But perhaps the use of this term in this context is misleading. Because REST refers to architectural constraints and is independent of language and platform, there is no simple, straightforward picture of what a «REST API» should look like. Numbers like the ones above probably include RESTful and REST-ish / REST services.
However, there is no denying that the development of the REST API has reached (and maintains) dominance in space. It is also clear that its main opposition is no longer SOAP, but GraphQL, newer and more elegant.
The future of REST / RESTful
In 2020, we noticed that 82% of APIs were RESTful (OpenAPI / Swagger) and 21% were RESTful (not OpenAPI / Swagger), while 19% used GraphQL. It is worth noting that GraphQL is not a direct «competitor» to REST, because it is a language rather than an architectural style. Despite this, some have supported it as an alternative to REST APIs since its introduction by Facebook.
There are a lot of articles about «Rest in Peace», which is a good pun to be fair. Many of them suggest or do not suggest that GraphQL will make REST irrelevant.
Well, now we are in 2021 and that has not happened yet.
Based on the numbers quoted above, the use of the REST architecture in public APIs decreased by only one percentage point. This is not surprising, given that reviewing an API requires an extraordinary amount of development and is not something to be taken lightly.
It remains to be seen whether GraphQL, or another exciting new approach to API development, will eliminate REST development in the next few years. However, for now, REST is still supreme, so you don’t need to remove all your RESTful APIs yet.