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 ▪ Github: github.com/toedter 4/30/2022 2 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License.
3. Show Hands! 4/30/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 4/30/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.” 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 5 Wikipedia Source: https://en.wikipedia.org/wiki/HATEOAS
6. 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 6 Root API
7. api.github.com 4/30/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 } } } 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 8
9. 4/30/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 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 10
11. HAL Structure 4/30/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" }, … ] } } 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 12
13. HAL Explorer ▪ Git Repo: https://github.com/toedter/hal-explorer ▪ Easy integration through WebJar ▪ Supports custom request headers ▪ Supports theming and responsive design ▪ Supported by Spring Data REST 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 13
14. HAL Explorer 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 14
15. 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 15 Demo
16. 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 16 Affordances
17. “ 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) 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 17
18. 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 ▪ … 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 18
19. 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 19 HAL-FORMS Image Source: http://wallpoper.com/images/00/26/43/92/hal-9000_00264392.jpg Shutdown! Restart
20. HAL-FORMS ▪ Designed to provide forms support for HAL ▪ Created by Mike Amundsen ▪ _templates for possible actions on self link ▪ Spec: https://rwcbook.github.io/hal-forms/ 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 20
21. “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.” 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 21 Mike Amundsen Source: https://rwcbook.github.io/hal-forms/
22. HAL-FORMS _templates (1) "_templates": { "default": { "title": "Create Movie", "method": "POST", "properties": [ { "name": "imdbId", "prompt": "IMDB Id", "required": true }, … © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 22
23. HAL-Explorer Template Elements 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 23
24. HAL-Explorer Request Input 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 24
25. HAL-FORMS Options 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 25 "properties" : [ { "name" : "...", "prompt" : "...", "options" : { "selectedValues" : ["...", "...", ...], "inline" : ["...", "..." , ...] | [{"prompt" : "...", "value" : "..."}, {...}, ...], "link" : { "href" : "...", "templated" : "true|false", "type" : "application/json|text/csv..." }, "promptField" : "...", "valueField" : "...", "minItems" : 0, "maxItems" : 1 } }
26. 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 26 "properties": [ { "name": "shipping", "prompt": "Select Shipping Method", "options": { "selectedValues": [ "FedEx" ], "inline": [ "FedEx", "UPS", "DHL" ], "maxItems": 1 } } ]
27. HAL-Explorer Options 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 27
28. 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 28 HAL-FORMS Demo
29. 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 29 Discussion
30. Links ▪ HAL-Explorer https://github.com/toedter/hal-explorer ▪ Movies Hypermedia Demo: https://github.com/toedter/movies-demo ▪ Spring HATEOAS: https://github.com/spring-projects/spring- hateoas 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 30
31. License ▪ This work is licensed under a Creative Commons Attribution 4.0 International License. ▪ See http://creativecommons.org/licenses/by/4.0/ 4/30/2022 © Kai Tödter, Licensed under a Creative Commons Attribution 4.0 International License. 31