Is REST and HATEOAS a good architecture for web services?

Question

If I understand correctly, REST was formalized by Roy Fielding as a descriptive model of the architecture of the web. AFAIK Fielding didn't claim REST was any good, he was just describing the de-facto architecture of the web. The web had already at this point proven an enormous successful distributed hypertext system, so this kind of validates REST as a successful architecture for the domain of distributed hypermedia primarily navigated and consumed by humans.

REST web services were created by applying REST architecture to API's. But is there actually any reason to think REST is a desirable architecture for this domain? More specifically, is there any evidence that says HATEOAS is a beneficial design principle for machine-to-machine communication?

My concern is that HATEOAS makes sense for hypermedia because there are few well-known content types (HTML, images, video etc) and the client knows how to consume them. But for API's the content types are very specific and can only be consumed in a meaningful way by the client if the client is specifically programmed to consume them. Returning an URL to the client does not in itself make the client able to consume the indicated resource.

Answer 1

AFAIK Fielding didn't claim REST was any good, he was just describing the de-facto architecture of the web.

That undersells it a bit, I would think. REST is, after all, an enumeration of the architectural style that Fielding was using as chief architect of the HTTP/1.1 spec.

But is there actually any reason to think REST is a desirable architecture for this domain? Is there any evidence that say HATEOAS is a beneficial design principle for machine-to-machine communication?

"It depends". HATEOAS is part of the uniform interface constraint of REST.

By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. Implementations are decoupled from the services they provide, which encourages independent evolvability. The trade-off, though, is that a uniform interface degrades efficiency, since information is transferred in a standardized form rather than one which is specific to an application's needs. The REST interface is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction.

So let's think for a moment about what this means. When I'm having trouble with my wireless router, I can communicate with it using the same browser that I use to submit answers to stackexchange. In particular, it doesn't matter what browser I'm using, or whether my browser is a few updates behind (or ahead) of what the router is expecting. It doesn't matter that the engineering organization that wrote the browser is completely independent of the organization that created the router interface.

It just works.

It's not, of course, universal. Fielding, in 2008, wrote:

That doesn’t mean that I think everyone should design their own systems according to the REST architectural style. REST is intended for long-lived network-based applications that span multiple organizations. If you don’t see a need for the constraints, then don’t use them.

The constraints that form the REST architectural style were chosen for the properties that they induce; if those properties aren't valuable to your use case, then you should absolutely be considering dropping the corresponding constraints.

Where machine to machine gets difficult, is that you've lost the ability of the human being to fuzzy match the semantics provided by the representations. The clients can get by with knowing just the media types, but we normally have a human being looking at the semantic cues to derive meaning.

schema.org is one part of an effort to create a machine readable vocabulary; the machine agents use the client to find the semantic hints, and applies its own understanding of the meaning to choose the correct actions to take.

But it's work; you need to invest in developing machine friendly representations of your resources, and ensuring that those representations remain forward and backwards compatible, so that clients can be developed independently.

When a single organization controls both the client and the server, the benefits of this independence are a lot smaller, in which case the constraint may not be an appropriate architectural choice.

Answer 2

No, 'full REST' is not that great.

As evidenced by the lack of people who implement HATEOS in thier APIs and the endless arguments over which HTTP verb to use for a particular call.

But you have to recognise why REST is so popular. Prior to its adoption there were various crazy complicated protocols such as ebXML and SOAP involving acknowledgements, timeouts, conversation Ids and state.

Getting these things up and running and then explaining them to consumers of the api was hard task. "why don't i just do a GET with the id I want in the query string and you send me the data?" was an obvious and common question.

Then the second problem was XML, javascript didnt understand it, schemas were a pain in the arse and you would end up with huge txt files mostly consisting of <MyLongObjectName>. So people started using JSON instead.

Now REST has a bit of a cult around it, but because the rules are so vague it doesn't prevent you knocking up a usable API which is simple enough that consumers will 'just get it' and use it without a 6 month on boarding process.

Answer 3

It is to note that Roy was not the original inventor of most of the principles of REST, he puts together many principles that are known to work in previous systems to solve various specific problems. REST is simply the natural conclusion of applying these principles in a single architecture.

Even before Roy Fielding wrote his dissertation on REST, the HTTP was already designed around the principles that later becomes known as REST. In the conclusion of his dissertation, he wrote:

At the beginning of our efforts within the Internet Engineering Taskforce to define the existing Hypertext Transfer Protocol (HTTP/1.0) [19] and design the extensions for the new standards of HTTP/1.1 [42] and Uniform Resource Identifiers (URI) [21], I recognized the need for a model of how the World Wide Web should work. This idealized model of the interactions within an overall Web application, referred to as the Representational State Transfer (REST) architectural style, became the foundation for the modern Web architecture, providing the guiding principles by which flaws in the preexisting architecture could be identified and extensions validated prior to deployment.

REST and HATEOS is a good fit for the problem it was designed for:

REST is a coordinated set of architectural constraints that attempts to minimize latency and network communication while at the same time maximizing the independence and scalability of component implementations. This is achieved by placing constraints on connector semantics where other styles have focused on component semantics. REST enables the caching and reuse of interactions, dynamic substitutability of components, and processing of actions by intermediaries, thereby meeting the needs of an Internet-scale distributed hypermedia system.

However, it should be noted that the Web and REST is not necessarily a good fit for every problems:

Likewise, proposed extensions can be compared to REST to see if they fit within the architecture; if not, it is more efficient to redirect that functionality to a system running in parallel with a more applicable architectural style.

So if your question is "Is REST and HATEOAS a good architecture for web services?" then, the answer is simply "yes, it is a good architecture for web services". The problem really is whether all the problems that people tried to solve by retrofitting them into the web constraints, really should have been web services in the first place.

There are many APIs which really does not fit REST. APIs that don't need the kind of scalability that REST are designed to solve, aren't consumed by multiple organizations that may evolve independently, and don't need to be long-lived; for these problems, the REST constraints are just a straitjacket.

But is there actually any reason to think REST is a desirable architecture for this domain? More specifically, is there any evidence that say HATEOAS is a beneficial design principle for machine-to-machine communication?

The evidence is the success of the Web at solving many people's problems. REST is a hybrid architecture, which combines the designs of many previous architectural styles. Many problem domains does not have all the requirements of the Web, and doesn't need to obey all the constrains of REST to perform well. This is why there are many successful architectures that works fine by just applying some parts of REST but not the others. HATEOAS and Uniform Interface, for example, are principles that are often skipped by APIs that doesn't need to cross organizational boundaries and systems which has relatively short deprecation period.

Answer 4

In Fielding's presentation on Adobe Experience Manager:

REST is NOT an architecture!

Rest is an architectural style, which is abstraction of different architecture that exists on the internet.

REST is an accumulation of design constraints to induce architectural properties

REST is a buzzword, and everyone wants to have RESTful API. In reality, when people faced with REST constraints, they dropped some of these constraints because there were no need or no benefit to be gained for them to apply all the constraints.

As you mentioned, HATEOAS is useful when the client is a web browser. When the client is a mobile app, maybe not so much. It would be good practice, but there are also costs associated to design an application like that, so much so that, to give example, the mobile app team and the back end team just agreed to drop that constraint. And that kind of make sense because both teams are not that loosely coupled because they work for the same company.

REST in AEM

Answer 5

if what you want is to create a service which is consumed by another server, then xmlrpc is the correct choice. If what you want is a service to be consumed by thin clients or low power devices.. or unknown clients over the open internet the perhaps consider rest using json. But remember, json is an inferior notation for specifying general data, when compared to xml.