HAL-Explorer: The easiest way to explore HAL/HAL-FORMS based APIs

This slide deck introduces my Open Source Project "HAL-Explorer", see https://github.com/toedter/hal-explorer

Transcript

1. The easiest way to explore HAL/HAL-FORMS based APIs Kai Tödter
2. Who am I? ▪ Principal Key Expert at Siemens Smart Infrastructure ▪ Web Technology Fan ▪ Open-Source Lover ▪ E-mail: kai@toedter.com ▪ 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.
3. Show Hands! 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 3
4. 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
5. “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
6. 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 6 Root API
7. 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", … }
8. 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
9. 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
10. 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
11. 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
12. 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
13. 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
14. HAL Explorer 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 14
15. 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 15 Affordances
16. “ 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
17. 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
18. 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
19. 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
20. “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/
21. 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
22. 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
23. 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 23 Demo
24. 11/11/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 24 Discussion
25. 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
26. 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