Can someone explain “Hypertext as engine of applic

Question

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.

Answer 1

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.

Answer 2

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.

Answer 3

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.