tags:

views:

348

answers:

4

This seems to be the REST principal that I've had the hardest time wrapping my head around. I understand that when desiging a rest api most of the effort should go into designing/describing hypertext for the application. Any pointers to real world applications of this principal ? How does atom protocol apply this principal ? Can some one explain that in simple terms how one would apply that to a hypothetical shopping cart rest api.

A: 

This article provides some samples in the context of Flickr.

Hypermedia in RESTful applications

dommer
Flickr is not RESTful. They're lying. Fielding himself, the creator of REST, says Flickr has no idea what they are doing.
Wahnfrieden
+3  A: 

Consider yourself navigating a regular website. When you visit, you read the contents of the pages, and based on what you've read and what you want to do, you follow various links on the page. That's really the core of what "hypertext as the engine of application state" boils down to. In this example, application state is the state in your head and the page you're on. Based on that, you traverse further links, which alters the application state in your head.

There's one other element to it, mind: the other side of it is that you shouldn't need to guess those URIs: there should be enough context in the page to infer the URIs (such as the information the application would have of the content type, and things like URI template), or the URIs to follow should be present. Beyond that, a RESTful HTTP application shouldn't care about the structure of the URIs.

UPDATE: To expand on things, HTML forms demonstrate HATEOAS too. Forms that use GET are analogous to the use of URI templates. And HATEOS isn't limited to just traversing links using HTTP GET: forms using POST (or some other method, if the browser just happens to support it) can be though of as describing a representation to send to the server.

Keith Gaughan
Ok so based on what you are saying url template schemes are evil and application should provide next options via schemes like <a> tags.How does a shopping cart media ( say xml ) say next you can pay with your credit card . Any examples to that effect ? Thanks for the response.
Surya
URI template schemes are evil if the application needs to have prior knowledge of them, i.e., if their hardcoded into the client application. OpenSearch is a good example of how to use URI templates properly. But if the client if fixated on the URIs looking a certain way, that ain't REST.
Keith Gaughan
No, if the client is using URI templates that it acquired from the server, that's a different story, hence my example of OpenSearch. The server is telling the client how to build URIs there and then rather than the client depending on a-priori out-of-band knowledge.
Keith Gaughan
A full shopping cart example is going to take time though! I'll see if I can write up an article on it this evening.
Keith Gaughan
I don't see how REST is appropriate for shopping cart customer interaction flow.
Wahnfrieden
It's perfectly fine because the shopping cart and products can be modelled as resources. But note that REST has nothing about interactions or workflows - that's really all down the particular application.
Keith Gaughan
A: 

Another way to look at this concept is that the state is represented by the current page and the links embedded in it. Traversing a link changes the state of the application which is represented by the next page. It is a little hard to explain... the links that are available at any point in time define what actions are available based on the actions that have already occurred. This is one definition of "the current state".

The trick is to represent the available actions are URIs which "act" on a resource. Retrieving the representation associated with a URI implicitly performs the action and retrieves the representation that results. URIs are embedded in the representation and the user understands the action associated with a specific URI. The various HTTP methods help define the "actions" that occur and specifies when no action is allowed. This is usually what people are getting at when describing the whole RESTful paradigm.

D.Shawley
I don't think this is quite accurate. In e.g. HTTP, the only "actions" you can do are GET, POST, PUT, and DELETE. In REST, you aren't representing available actions as URIs, you are exposing resources via URIs and letting people GET, POST, PUT and DELETE them.
Steven Huwig
Using HTTP verbs correctly is not REST. It's simply using HTTP correctly.
Wahnfrieden
+4  A: 

When attempting to explain hypermedia, I like to use the example of navigating in a car via signposts versus a map. I realize it doesn't directly answer you question but it may help.

When driving a car and you reach a particular intersection you are provided signposts to indicate where you can go from that point. Similarly, hypermedia provides you with a set of options based on your current state.

A traditional RPC based API is more like a map. With a map you tend to plan your route out based on a static set of road data. One problem with maps is that they can become out of date and they provide no information about traffic or other dynamic factors.

The advantage of signposts is that they can be changed on the fly to detour traffic due to construction or to control traffic flow.

I'm not suggesting that signposts are always a better option than a map. Obviously there are pros and cons but it is valuable to be aware of both options. It is the same with hypermedia. It is a valuable alternative to the traditional RPC interface.

Darrel Miller
Great example . <a> links in html analogous to signposts i guess..right?
Surya
Exactly. I guess I should have spelled that out.
Darrel Miller
One small clarification: "a set of options based on your current state" should probably be "a set of options based on the resource state", since the client isn't supposed to have state. With your analogy, your current location is the resource.
Chris Winters
That is a an interesting distinction. Actually the client does have "application state". Your current location is the client state. The important thing is that the server is not aware of the client state. The available options however are only dependent on the location if you ignore security.
Darrel Miller
In a way both statements are correct. A traffic light may be green or red irrelevant of whether you are standing in front of it or not. However, your options are very much dependent on your current location.
Darrel Miller