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

Pragmatic Hypermedia

Pragmatic Hypermedia

A pragmatic take on how to use hypermedia in our APIs. In this talk we take a look at some of the difficulties in many hypermedia approaches and finish up with a look at RESTful JSON.


Stephen Mizell

September 26, 2018


  1. Pragma&c Hypermedia

  2. Hi, I'm Stephen Mizell @Stephen_Mizell

  3. I'm here to share some ways I've changed how I

    think and talk about hypermedia
  4. A quick story of hypermedia and API standards

  5. We felt the hypermedia gap

  6. None
  7. The costs of moving to hypermedia • Selec&ng the right

    media types for the right situa&on • Understanding how to use link rela&ons and document them • Picking the libraries to handle hypermedia • Passing these requirements to the API consumers • Giving up familiar tools • Understanding separate, exclusive terminology
  8. None
  9. Closing the hypermedia gap • Enable people to con-nue using

    their tools • Help find common processes • Share best prac-ces where prac-cal • Shi: to inclusive terminology
  10. What do we mean by pragma1c? We determine the success

    of ideas based on their prac3cal applica3on.
  11. None
  12. Now what are we trying to accomplish with hypermedia?

  13. Within bodies of wri/ng, everywhere, there are linkages we tend

    not to see. The individual document, at hand, is what we deal with; we do not see the total linked collec/on of them all at once. But they are there, the documents not present as well as those that are, and the grand cat’s-cradle among them all. — Ted Nelson
  14. Being able to see visible connec/ons between pages seems to

    me absolutely fundamental. — Ted Nelson
  15. "As I've previously said..."

  16. Everything is deeply intertwingled. — Ted Nelson

  17. Non-hierarchical Non-linear Visible links

  18. But instead of going back to the past, we should

    transcend and include.
  19. People seem to want this interconnectedness —consider GraphQL.

  20. Hypermedia is about designing and building applica0ons that express the

    interconnectedness of the domain and allow for those connec0ons to change over 0me.
  21. Pragma&c hypermedia is then concerned with finding prac1cal ways to

    express interconnectedness without forcing people to leave everything behind.
  22. Back to the original story

  23. "Have you looked into Stripe's API?"

  24. Stripe API JSON { "url": "/v1/customers", // ... "hosted_invoice_url": "...",

  25. The more we looked, the more we found this pa5ern

    used all over.
  26. RESTful JSON is a minimal and pragma,c design pa/ern for

    using links to build expressive and evolvable APIs. h"p:/ /res)uljson.org
  27. Two simple rules 1. JSON objects MAY include a url

    property to indicate a link to itself 2. JSON objects MAY append _url to proper>es to indicate related links
  28. RESTful JSON example { "url": "...", "title": "Article Title", "body":

    "The body of the article.", "author_url": "...", "profile_url": "http://example.com/profile/article" }
  29. It may miss the mark when compared to modern hypermedia

    concepts and prac3ces.
  30. Yet in the context of the API standards, people picked

    up RESTful JSON quickly.
  31. What are some prac-cal things ways you can use it

    for hypermedia?
  32. Use a url instead of database IDs

  33. Use links for rela-onships instead of nested resources { "url":

    "...", "first_name": "John", "last_name": "Doe", "orders_url": "..." } Instead of appending resource names /customers/4/orders
  34. Use links to show available ac1ons { "url": "...", "disable_url":

    "..." }
  35. Condi&onally render parts of the UI (Vue.js example) <div v-if="hasDisableLink">

    <button type="button">Disable</button> </div>
  36. Use links to for applica0on flow like pagina0on { "url":

    "...", "next_url": "...", "prev_url": "..." }
  37. Documen(ng in OpenAPI Schemas schema: type: object properties: orders_url: type:

    string format: url
  38. Final takeaways • Find ways to empower people to get

    hypermedia's benefits • Consider the costs of hypermedia • Look for prac<cal solu<ons to the costs • Think of other ways to express the intertwingularity of your app
  39. Thanks!