The easiest way to explore HAL/HAL-FORMS based APIs Kai Tödter

Who am I? ▪ Principal Key Expert at Siemens Smart Infrastructure ▪ Web Technology Fan ▪ Open-Source Lover ▪ E-mail: [email protected] ▪ Twitter: twitter.com/kaitoedter ▪ Mastodon: https://mastodon.social/@kaitoedter ▪ Github: github.com/toedter 11/11/2022 2 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License.

Show Hands! 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 3

HATEOAS ▪ Is for “Hypermedia As The Engine Of Application State” ▪ Very hard to pronounce ☺ ▪ Key concept of REST 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 4

“With HATEOAS, a client interacts with a network application whose application servers provide information dynamically through hypermedia. A REST client needs little to no prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia.” 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 5 Wikipedia Source: https://en.wikipedia.org/wiki/HATEOAS

11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 6 Root API

api.github.com 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 7 { "current_user_url": "https://api.github.com/user", "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}", "authorizations_url": "https://api.github.com/authorizations", "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}", "commit_search_url": "https://api.github.com/search/commits?q={query}{&page,per_page,sort,order}", "emails_url": "https://api.github.com/user/emails", "emojis_url": "https://api.github.com/emojis", "events_url": "https://api.github.com/events", "feeds_url": "https://api.github.com/feeds", "followers_url": "https://api.github.com/user/followers", "following_url": "https://api.github.com/user/following{/target}", "gists_url": "https://api.github.com/gists{/gist_id}", "hub_url": "https://api.github.com/hub", "issue_search_url": "https://api.github.com/search/issues?q={query}{&page,per_page,sort,order}", "issues_url": "https://api.github.com/issues", … }

Movies Root API { "_links": { "self": { "href": "http://localhost:8080/api" }, "movies": { "href": "http://localhost:8080/api/movies{?size,page}", "templated": true }, "directors": { "href": "http://localhost:8080/api/directors{?size,page}", "templated": true } } } 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 8

11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 9 HAL Image Source: http://wallpoper.com/images/00/26/43/92/hal-9000_00264392.jpg

HAL ▪ Is for Hypertext Application Language ▪ Created by Mike Kelly ▪ Representations for both JSON and XML ▪ Very popular & very simple ▪ Spec: https://tools.ietf.org/html/draft-kelly- json-hal-08 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 10

HAL Structure 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 11 Plain old JSON Properties Links Plain old JSON Properties Links Plain old JSON Properties Links … Embedded Resources Embedded Resources Embedded Resources

HAL Example { "name": "Ridley Scott", "_links": { "self": { "href": "https://movies-demo.org/api/directors/89", }, "movies": [ { "href": "https://movies-demo.org/api/movies/93", "title": "Alien" }, … ] } } 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 12

HAL Explorer ▪ https://github.com/toedter/hal-explorer ▪ Easy integration through WebJar ▪ Supports custom request headers ▪ Supports theming and responsive design ▪ Supported by Spring Data REST 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 13

HAL Explorer 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 14

11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 15 Affordances

“ 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.” James J. Gibson The Ecological Approach to Visual Perception (1986) 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 16

Affordances ▪ With Affordances, possible actions on a REST resource (or Link relation) can be described in more detail, e.g. ▪ What can you do with a REST resource? ▪ Create, Update, Delete, … ▪ Which parameters are mandatory or optional ▪ How would (internationalized) labels be displayed in a user interface ▪ … 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 17

11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 18 HAL-FORMS Image Source: http://wallpoper.com/images/00/26/43/92/hal-9000_00264392.jpg Shutdown! Restart

HAL-FORMS ▪ Designed to provide forms support for HAL ▪ Created by Mike Amundsen ▪ _templates for possible actions ▪ Spec: https://rwcbook.github.io/hal-forms/ 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 19

“The HAL-FORMS media type design follows many of the HAL media type conventions. For this reason, HAL-FORMS "looks like HAL." However, it is important to keep in mind that HAL-FORMS is not the same as HAL — the two should not be thought of as interchangeable in any way.” 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 20 Mike Amundsen Source: https://rwcbook.github.io/hal-forms/

Rendering with HAL-FORMS (1) "_templates": { "default": { "title": "Change Movie", "method": "PUT", "contentType": "", "properties": [ { "name": "imdbId", "prompt": "IMDB Id", "required": true }, … © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 21

Rendering with HAL-FORMS (2) "_templates": { "default": { … }, "deleteMovie": { "title": "Delete Movie", "method": "DELETE", "contentType": "", "properties": [] } } © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 22

11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 23 Demo

11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 24 Discussion

Links ▪ Movies Hypermedia Demo: https://github.com/toedter/movies-demo ▪ Spring HATEOAS: https://github.com/spring-projects/spring- hateoas 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 25

License ▪ This work is licensed under a Creative Commons Attribution 4.0 International License. ▪ See http://creativecommons.org/licenses/by/4.0/ 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 26