Can someone explain “Hypertext as engine of application state" in simple terms

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

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.

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.