Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

A0aae1297a0593c1316abdcdb4131e3a?s=128

Kai Toedter

April 28, 2022
Tweet

More Decks by Kai Toedter

Other Decks in Programming

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