Hypermedia Cannot be the Engine
13 likes4,374 views
This document discusses the principles of REST APIs and hypermedia. It argues that while hypermedia is useful for navigating a single API, it is not sufficient on its own for describing cross-API interactions. The document advocates combining self-descriptive representations of an API's responses with self-descriptive descriptions of an API's functionality to fully support how clients may use the API.
Hypermedia Cannot be the Engine
- 1. HYPERMEDIA cannot be the engine HYPERMEDIA cannot be the engine Ruben Verborgh Ghent University – iMinds
- 2. “REST APIS MUST BE HYPERTEXT-DRIVEN.” Roy T. Fielding
- 3. HYPERMEDIA cannot be the engine Hypermedia Heaven & Hell Self-descriptive Salvation Angels of Affordance
- 4. REST “REDUCES COUPLING”. WS-*/ESB RPC over HTTP RESTful HTTP Deg Loo Tigh Des Discovery Identification Binding Platform Interaction Interface Orientation Interface Orientation Model Granularity State Evolution Generated Code Generated Code Conversation Discovery Identification Binding Platform Interaction Model Granularity State Evolution Conversation (a) RESTful HTTP (b) RPC over HTTP Figure 3: Measuring the degree of coupling implied by different W RESTful HTTP RPC over HTTP REST RPC C. Pautasso & E. Wilde, “Why is the Web Loosely Coupled? A Multi-Faceted Metric for Service Design”
- 5. REST HAS A UNIFORM INTERFACE. resources representations self-descriptiveness hypermedia
- 6. RESOURCES identify resources, not actions resources are cacheable
- 7. REPRESENTATIONS share identifiers across systems different needs, different representations
- 8. SELF-DESCRIPTIVENESS no external documentation clients interpret representations
- 9. HYPERMEDIA no hard-coded URLs retrieve a resource, follow links
- 10. SO FAR FROM HEAVEN so close to hell.
- 11. DOES SELF-DESCRIPTIVENESS REDUCE COUPLING? YES. only the message itself is needed for interpretation “in-band”
- 12. DOES SELF-DESCRIPTIVENESS REDUCE COUPLING? NO. REST APIs rely on media types. “in-band”??
- 13. SO YOU UNDERSTAND JSON? application/alto-costmap+json application/alto-costmapfilter+json application/alto-directory+json application/alto-endpointprop+json application/alto-endpointpropparams+json application/alto-endpointcost+json application/alto-endpointcostparams+json application/alto-error+json application/alto-networkmapfilter+json application/alto-networkmap+json application/jrd+json application/json application/json-patch+json application/ld+json application/reputon+json application/vcard+json application/vnd.api+json application/vnd.bekitzur-stech+json application/vnd.collection.doc+json application/vnd.collection+json application/vnd.collection.next+json application/vnd.document+json application/vnd.hal+json application/vnd.heroku+json application/vnd.oftn.l10n+json application/vnd.siren+json application/vnd.xacml+json
- 14. DOES SELF-DESCRIPTIVENESS REDUCE COUPLING? Clients can interpret the message using only in-band information… …if they understand the media type… …which is out-of-band.
- 15. DOES HYPERMEDIA REDUCE COUPLING? In each representation, the server includes links towards other resources.
- 16. DOES HYPERMEDIA REDUCE COUPLING? YES. Clients don’t hard-code a server’s URLs. Clients don’t hard-code the path to information.
- 17. DOES HYPERMEDIA REDUCE COUPLING? In each representation, the server includes links towards other resources. NO. How can the server know what links its clients need?
- 18. DOES HYPERMEDIA REDUCE COUPLING? The server sends you an image. Scale it. Crop it. But you want to do something else. Black & white. Make profile pic.
- 19. HYPERMEDIA cannot be the engine media type coupling affordance coupling
- 20. HYPERMEDIA cannot be the engine Hypermedia Heaven & Hell Self-descriptive Salvation Angels of Affordance
- 21. ENOUGH WITH THE MEDIA TYPES ALREADY.
- 22. CHOOSE A SELF-DESCRIPTIVE MEDIA TYPE. JSON is just JSON. “image” likely has a hundred meanings.
- 23. CHOOSE A SELF-DESCRIPTIVE MEDIA TYPE. JSON-LD is self-descriptive. “image” is actually a URL. Clients can look it up.
- 24. CHOOSE A SELF-DESCRIPTIVE MEDIA TYPE. The client still has to understand this media type. But it’s not task- or application-specific.
- 25. ADD SELF-DESCRIPTIVE HYPERMEDIA CONTROLS. <form> <label>Person:</label> <input name=“person” /> </form> What does this do?
- 26. ADD SELF-DESCRIPTIVE HYPERMEDIA CONTROLS. Hydra inside JSON-LD response relate controls to data properties
- 27. DESCRIBE THE API BEFOREHAND. in a hypermedia-based way describe the links (imageA) —B&W—> (imageB)
- 28. DESCRIBE THE API BEFOREHAND. in a resource-based way describe the functionality (imageA) ——> (imageB&W)
- 29. HYPERMEDIA cannot be the engine Hypermedia Heaven & Hell Self-descriptive Salvation Angels of Affordance
- 30. HYPERMEDIA RESPONSES SHOULD AFFORD GOING TO NEXT STEPS. Server: Here’s an image. Client: Thanks. I want to scale it. Server: I thought you would, so I included a link.
- 31. HYPERMEDIA RESPONSES SHOULD AFFORD GOING TO NEXT STEPS. Client: Now use it as my Facebook profile picture. Server: Err… why would you want to do that?
- 32. IT’S HARD TO IMAGINE ALL WAYS IN WHICH CLIENTS USE YOUR API. IMPOSSIBLE SELF-DESCRIPTIVENESS GIVES THEM A CHOICE.
- 33. COMBINE SELF-DESCRIPTIVENESS OF AN API’S RESPONSES… …WITH SELF-DESCRIPTIVENESS OF AN API’S FUNCTIONALITY “This is a photo of Ellen.” “This API takes an image, returns a black & white version.”
- 34. …TO COMPLETE THE INTERACTION THAT HYPERMEDIA COULDN’T.
- 35. HYPERMEDIA can be the engine of a single API. HYPERMEDIA cannot the engine of cross-API interactions.
- 36. BUILDING API DESCRIPTIONS is thinking about Web APIs on a Web scale.