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
Tweet

More Decks by Stephen Mizell

Other Decks in Technology

Transcript

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

    think and talk about hypermedia
  2. 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
  3. 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
  4. What do we mean by pragma1c? We determine the success

    of ideas based on their prac3cal applica3on.
  5. 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
  6. Being able to see visible connec/ons between pages seems to

    me absolutely fundamental. — Ted Nelson
  7. Hypermedia is about designing and building applica0ons that express the

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

    express interconnectedness without forcing people to leave everything behind.
  9. 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
  10. 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
  11. RESTful JSON example { "url": "...", "title": "Article Title", "body":

    "The body of the article.", "author_url": "...", "profile_url": "http://example.com/profile/article" }
  12. 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
  13. Use links to for applica0on flow like pagina0on { "url":

    "...", "next_url": "...", "prev_url": "..." }
  14. 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