Representational State Transfer (REST) is one of the hottest API design styles out there. It was originally defined in Roy Fielding’s Ph.D. dissertation from the year 2000, and has since been a staple of the API economy… or so we like to tell ourselves! In truth, many of the world’s so-called “REST” APIs fail to adhere to one or more of the style’s defining criteria. While these REST-like APIs are straightforward to create and consume, some say they don’t quite offer the same benefits that a pure REST API would. In this article, we’ll look closely at how a true REST API differs from a REST-like API, and discussing the pros and cons of those differentiating features.

REST vs. REST-Like APIs

According to Zdenek Nemec, author of the API Blueprint description language, the key difference between REST and REST-like APIs is that the latter does not fulfill a defining constraint of REST: uniform interface. As such, establishing the theoretical and practical distinctions between these two API styles calls for a detailed understanding of the uniform interface.

What Is Uniform Interface?

Let’s start by breaking down uniform interface on a literal level. With any API, the interface is what the client sees when interacting with the API. REST calls for this to be uniform (read: consistent), so that a client consuming the API — or a new version of the same API — for the first time can intuitively know how to interact with it.

In his dissertation, Fielding writes:

“In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and hypermedia as the engine of application state.”

That’s right — uniform interface itself consists of four constraints. Here they are explained:

Identification of Resources

The first constraint of uniform interface is how resources are identified. This means that REST APIs should enable clients to identify a resource by means of a URI contained within the request.

Some add that the representation of a resource returned to the client should be separate from the resource itself. In other words, the RESTful representation of a resource should not represent the service’s internal representation of that resource, assuming the two are different.

Manipulation of Resources Through Representations

The second constraint of uniform interface is the manipulation of resources through their representations. Specifically, given the representation of a resource and any metadata associated with it, the client should be able to modify or delete the resource.

In practice, this really just means of available HTTP methods. The DELETE method should enable clients to delete a resource having just its URI, while the PUT and PATCH methods should enable clients to modify a resource having its URI and representation.

This approach to manipulating resources does away with long, verb-based API endpoints (e.g. updateUserAddress), instead of providing a uniform alternative… hence it’s part of uniform interface!

Self-Descriptive Messages

The third constraint of uniform interface is that messages are self-descriptive. This means that the representation of a resource should be returned to the client along with information on how to process it.

With REST APIs, the HTTP Content-Type header should be used to tell the client what media type is being sent in the body. In the interests of standardization, this should ideally be an IANA-registered media type — such as application/json for a JSON response. Non-IANA media types can also be used, but they must be agreed upon with clients.

Hypermedia as the Engine of Application State (HATEOAS)

The fourth and final constraint of uniform interface is that application state should be expressed dynamically through hypermedia (known in short as HATEOAS). This means that in addition to returning a representation of the resource in question, a request should also be met by instructions on how to further interact with the resource or API as a whole.

In particular, upon accessing a resource, the client should be provided with information as to what actions can be performed on that resource. These actions should be accompanied by hyperlink references to relevant URIs.

HATEOAS: The Defining Constraint of REST

If you look at the first three components of uniform interface — identification of resources; manipulation of resources through representations; and self-descriptive messages — you’ll notice that most REST-like APIs successfully address these issues:

• URIs are used to identify resources
• Resources can be manipulated (intuitively) having their representations
• Responses are self-descriptive, usually thanks to the Content-Type header

Indeed, it’s the last of these constraints — HATEOAS — that prevents many APIs from earning the glorious title of a REST API. While these REST-like APIs are structured around resources and put plenty of HTTP groundwork to use, they do not navigate clients through the interface by means of hyperlinks.

Funnily enough, this use of hypermedia is also what defines the third level of the Richardson Maturity Model for evaluating APIs.

Pros and Cons of HATEOAS; or REST vs. REST-like APIs

Whether an API is genuinely a REST API or just REST-like, boils down to whether it implements HATEOAS. So, to compare the two styles, all we have to do is look at the pros and cons of hypermedia usage.

Pros

Evolvability: Having clients dynamically interact with your API makes it significantly easier to evolve your API — you can modify or move functionality without the need for versioning
(see this Tweet)
Discoverability: Telling clients what further actions are available enables effective discovery of the functionality offered within your API, reducing the need for detailed documentation
Simplicity: Telling clients what further actions are available minimizes client-side logic, streamlining and simplifying the integration

Cons:

Lack of adoption: Due to old habits and a lack of tools and standards, most clients will not consume your API dynamically
Development needs: Implementing hypermedia lengthens the development process, increasing both cost and time to market
Dependencies: Making use of hypermedia frameworks, like Hydra, Siren, or JSON Hyper-Schema, can introduce new dependencies to the API.

All in all, the true REST approach promises significant benefits — most notably, boundless evolvability — thanks to its use of hypermedia. In practice, however, REST-like APIs often meet clients’ needs without the added developmental challenges.

Final Thoughts

The key difference between REST and REST-like APIs lies in the constraint of uniform interface — in particular, hypermedia as the engine of application state. While true REST, by definition, mandates the use of hyperlinks to navigate clients through the interface, REST-like APIs fail to do so, usually meeting all of the style’s remaining constraints. Hypermedia as the engine of application state is clearly an interesting ideal, but lacks practicality in both adoption and implementation.