141

as everyone may have noticed, there are lot of fake/rudimentary REST-APIs in the wild (which implement a HTTP-API and call it REST without following the hypertext-as-the-engine-of-application-state requirement, which led to the famous rant of Roy T. Fielding, the man who first specified the REST-paradigm).

I've been unable to find any practical examples of a truly hypertext driven REST-implementation along with the associated application-specific media-type definitions for the state transitions.

Are there any publicly accessible examples of such implementations?

General Grievance
  • 4,555
  • 31
  • 31
  • 45
pmf
  • 7,619
  • 4
  • 47
  • 77
  • 3
    I find this interesting since many people claim REST is "easy" but Fielding himself says that although it is a simple architecture, it is not simple to design an application with it. – aehlke Jul 21 '09 at 20:47
  • 3
    by the way, it should be HATEOAS not HATEOS, the later doesn't google well. – David Roussel Jul 19 '10 at 15:01
  • 1
    http://restcookbook.com/Basics/hateoas/ – Ben Nov 04 '13 at 09:50
  • 2
    Paypal seems to use it: https://developer.paypal.com/docs/integration/direct/paypal-rest-payment-hateoas-links/ – Andrew Thaddeus Martin May 21 '15 at 16:30
  • Has Roy Fielding himself ever built an application using HATEOAS? – Geoffrey Dec 24 '18 at 10:38
  • Just stumbled upon this, and couldn't help but laugh. 10 years later, everyone is still confused. Fielding's REST was not meant to be a better way to do web services. It's a generalized description of the architecture of the Internet. You want an example of an application that uses HATEOAS? It's the *goddamn Internet*! To us it's a platform, but for the people that built it, it was an application. REST describes the unique needs of *internet-scale* applications - not your run of the mill web services. The industry's idea of REST has nothing to do with that. Same name, two different things. – Filip Milovanović Aug 20 '19 at 13:59

5 Answers5

103

Its not an implementation in the sense of running code, but I really like the article "How to GET a cup of coffee" on InfoQ. It describes the process of ordering a coffee at Starbucks as a RESTful protocol. This goes beyond the typical "everything is a resource" REST introductory article and focuses on HATEOAS. Highly recommended.

trendels
  • 4,747
  • 3
  • 26
  • 16
  • 5
    The book "Rest in Practice" by Jim Webber, Sayas Parastatidis and Ian Robinson is quite usefull – DomreiRoam Jun 23 '11 at 14:48
  • 2
    The article is fine, but unfortunately the API it describes doesn't strictly adhere to the HATEOAS principle because it doesn't use custom media types. How would the client know how to manipulate (e.g. deserialize, parse, display) each resource if everything is application/xml? It would depend on some non-standard ways of passing this information, like documentation meant to be read by humans. – ygormutti Oct 14 '15 at 20:34
22

How about the Sun Cloud API? From the introduction:

The API presupposes no particular structure in the URI space. The starting point is a URI, supplied by the cloud service provider, which identifies the cloud itself. The cloud's representation contains URIs for the other resources in the cloud, and also for operations which may be performed upon them (for example deploying and starting virtual machines).

The backstory might also be helpful.

Zoltan
  • 2,928
  • 11
  • 25
Rich Apodaca
  • 28,316
  • 16
  • 103
  • 129
7

Netflix has a REST API based on HATEOAS that includes links as part of the resources.

Al-Mothafar
  • 7,949
  • 7
  • 68
  • 102
Will Sargent
  • 4,346
  • 1
  • 31
  • 53
3

I realized this was asked a while ago, but I took a stab at demonstrating a "proper" REST API flow for a simple example. I tried to follow Roy's rules for REST - perhaps it could help: API Example using REST

jeremyh
  • 5,233
  • 3
  • 23
  • 19
3

Isn't the RESTfulness of Sun Cloud API actually addressed in Roy's 4th point:

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling].

Example 1 Fixed resource names in a defined heirachy:

From the Sun Cloud API: "... the representation of a VDC will include representations of the Clusters which inhabit it, which in turn include representations of the VMs within each cluster."

Example 2 out-of-band information, such as a domain-specific standard:

You have to have the wiki-page contents (out-of-band information) to know that the "resource communication mechanism" for the Cloud resource field "uri" is GET.

Hedgehog
  • 5,487
  • 4
  • 36
  • 43
  • 2
    You are correct, that is very misleading. However, Roy is talking about resource names in the uri space, not within the contents of the media type. Sun is free to change the uri that is used to access a cluster at any time. Obviously, it can't change the term "cluster" to "group" inside the representation without creating a new version of the media type, but it can change the URI to be anything. – Darrel Miller Feb 03 '10 at 03:18
  • 4
    We know that the Sun API uses HTTP as its uniform interface, so the client does not need to look at the wiki-page to know that GET is a valid verb for the cloud resource. It can either just try it considering it knows that GET is a safe verb, or it can use OPTIONS to determine if it is available. – Darrel Miller Feb 03 '10 at 03:21