Building richer hypermedia with Spring HATEOAS

Greetings Spring community,

As previously announced, we have released a new Affordances API in 1.0.0.BUILD-SNAPSHOT. In this blog post, we’ll take a peek at exactly what this feature lets you do.

History of Affordances

For starters, what is an affordance? Doing a little archeology, Mike Admundsen, a REST advocate, has an article detailing the word’s origins, going back at least to 1986:

The affordances of the environment are what it offers …​ what it provides or furnishes, either for good or ill. The verb 'to afford' is found in the dictionary, but the noun 'affordance' is not. I have made it up (page 126).
— The Ecological Approach to Visual Perception (Gibson)

It then appeared in a psychology paper in 1988:

…​the term affordance refers to the perceived and actual properties of the thing, primarily those fundamental properties that determine just how the thing could possibly be used. (pg 9)
— The Design|Psychology of Everyday Things (Norman)

Finally, it can be found in none other than one of Roy Fielding’s presentations on hypermedia in 2008:

When I say Hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user obtains choices and selects actions (slide #50).
— Slide presention on REST (Fielding)

In all these situations, "affordance" refers to the available actions provided by the surrounding environment. In the context of REST, these are actions detailed by the hypermedia.

In the past, when people moved away from SOAP and its action-based tactics, they have struggled to document their APIs, many unaware that Roy Fielding built hypermedia into REST for this very purpose. By including data along with the controls to not just find related data, but to also use the data is key.

With a HAL document, clients are provided very simple affordances. The links are shown but nothing else about them. What you can do with the links and what it takes to interact with them is not detailed.