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

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

Kai Toedter
November 10, 2022

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

Kai Toedter

November 10, 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: [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.
  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