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.

Transcript

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
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
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.
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!