REST vs HTTP

REST is a popular style of architecting and designing Web applications, which are commonly served over HTTP. But what makes an API RESTful and what is a plain HTTP API? There seems to be a trend of calling any HTTP based API a REST API, even though the API doesn't fulfill all the constraints that REST requires. REST's creator Roy Fielding, also voiced his opinion about this in a blog post on his website:

I am getting frustrated by the number of people calling any HTTP-based interface a REST API.

— Roy Fielding, creator of REST

Let's take a quick look to review, what the REST and HTTP are:

Definitions

Representational state transfer (REST) is a software architectural style that defines a set of constraints to be used for creating Web services. Web services that conform to the REST architectural style, called RESTful Web services, provide interoperability between computer systems on the Internet. RESTful Web services allow the requesting systems to access and manipulate textual representations of Web resources by using a uniform and predefined set of stateless operations.

The Hypertext Transfer Protocol (HTTP) is an application protocol for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data communication for the World Wide Web, where hypertext documents include hyperlinks to other resources that the user can easily access, for example by a mouse click or by tapping the screen in a web browser.

The REST constraints

REST Web services must follow a set of 6 constraints. We will take a closer look at the following two:

Stateless communication
Uniform interface

Stateless communication means that communication between client and server cannot rely on previous requests. For example: Clients can not ask servers to send them "the next page", because doing so would require that the server maintained some state about, which page the particular client has seen last.

Instead, the uniform interface constraints impose a number of subconstraints namely, identification of resources; manipulation of resources through representations; self-descriptive messages; and hypermedia as the engine of application state(sometimes abbreviated as HATEOAS). This means that Hypertext(or more generally, hypermedia) needs to be the driving mechanism by which clients navigate through the application. Hypermedia is a data format that can be interlinked. HTML with its anchor tags is a good example, but any format with this capability will work.

So, by using hypermedia servers can directly send clients new URIs to navigate to. So instead of storing, which page a client has seen last, a server following a REST design will simply include a link to page 4 if it received a request for page 3. The client can then use it request the next page without the server having to maintain any client state.

REST aims to reduce coupling between client and server, so another big benefit of including hyperlinks to other resources in the response, is that the client does NOT need to know a catalog of available resources up front. It is enough for clients to navigate to the inital service URI and then follow links to other resources. This enables clients and servers to evolve independently because resources can be discovered and do not need to be know.

However, most APIs that are declared REST APIs by their makers, do not follow the constraint that client-server interaction must be hypertext-driven.(HATEOAS) Often APIs simply return some JSON and does not contain any links to other resources. This tighlty couples client and server because without links clients need knowledge of every endpoint up front and breaks RESTful design.

What REST IS NOT about

Pretty URIs like
```
/customer/12/profile
```
Having to use all of the HTTP methods like GET, POST, PUT, DELETE

What REST IS about

discoverability of resources
resources that are addressable
loose coupling between client and server
making use of existing standards: like HTML, HTTP, URI and standardized media types
long living systems that can evolve independently over time

Checklist: Is my API RESTful?

If you recognize these things in your application, there's a high chance, that REST constraints are violated.

Your clients are performing string concatenation to build resource URLs.
=> REST clients should have no knowledge of resource URLs other than the initial one. This demostrates a high coupling between client and server.
Server responses don't contain links to other resources
=> Violates hypertext/hypermedia constraint. In the inital response clients should receive links to other available resources.
Client says, give me the next page:
=> Violates stateless constraint. To fulfill that the server would have to keep track of what the "next page" actually is. The correct RESTful way of doing that would be if the server returns the current page along with a link to the next one, which can then be used by the client to retrieve the next page.

For a more comprehensive list, see Roy Fieldings blog.

REST FAQs

Does REST need to be served over HTTP?

Nope, there is no constraint that requires HTTP. REST happens to map very well to HTTP, though. In fact, Roy Fielding was also working on the HTTP/1.1 spec so there definitely has been some sort of influence. In practice, virtually all implementations of REST use HTTP, even though it is not a requirement.
Are all HTTP APIs automatically REST APIs?

No, only if they follow the constraints for REST, as laid out in Roy Fielding's dissertation.
What is hypertext/hypermedia and HATEOAS?

It is simply a data format that has a notion of linking to other content. HTML is a good example because it has anchor tags that connect to other documents. Clients(Browsers) know how to transition from one page(resource) to the other simply by understanding the Media type text/html.
What about other popular ways of building APIs, do they follow REST?

GraphQL: GraphQL is a query language and not an architectural style. GraphQL endpoints are actually somewhat discoverable due to their introspection queries, but they do not make use of hypermedia media types or preexisting semantics of a protocol like HTTP. GraphQL can be served over HTTP, but if it is then HTTP is treated as a dumb transportation layer.

gRPC: gRPC is a high performance Remote Procedure Call(RCP) framework. Since it is using RCP, it tightly couples client and server. This is often not a problem because there are tools that often generate client code from Protocol Buffer descriptions, but it violates REST principles.

JSON:api: JSON:api Is a specification for APIs using JSON. Although it does not explicitly label itself as following REST, it implements many constraints correctly and promotes a style, that it is plays well with REST constraints. This is includes using it's own media type application/vnd.api+json, using a JSON format that is registered with IANA (available to clients). This format can be seen as hypermedia, because it contains links to other resources (discoverable) such as "self", "next" or "last".

Conclusion

The REST architectural style as defined by Roy Fielding defines a set of constraints. A lot of times APIs that are called RESTful violate at least one of them. Most commonly they violate the Uniform interface constraint, because resources are not discoverable due to lacking links in responses.

Hopefully, this page has clarified what REST is and what it isn't. While reading, you may have detected a so-called REST API at work or another place, that actually should not be called one. If you did please:

Stop calling it a REST API.😉. This would make Roy Fielding happy as well.
Kindly, pass on this knowledge or the link to this website to other people, who you feel might benefit from learning what REST is truly about. 🙏