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

    View full-size slide

  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.

    View full-size slide

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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

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

    View full-size slide

  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",

    }

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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/

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide