HYPERMEDIA

cannot be the engine
HYPERMEDIA

cannot be the engine
Ruben Verborgh

Ghent University – iMinds
“REST APIS MUST BE

HYPERTEXT-DRIVEN.”
Roy T. Fielding
HYPERMEDIA

cannot be the engine
Hypermedia Heaven & Hell
Self-descriptive Salvation
Angels of Affordance
REST “REDUCES COUPLING”.
WS-*/ESB
RPC over HTTP
RESTful HTTP
Deg
Loo
Tigh
Des
Discovery
Identification
Binding
Platform
In...
REST HAS

A UNIFORM INTERFACE.
resources
representations
self-descriptiveness
hypermedia
RESOURCES
identify resources, not actions
resources are cacheable
REPRESENTATIONS
share identifiers across systems
different needs,

different representations
SELF-DESCRIPTIVENESS
no external documentation
clients interpret representations
HYPERMEDIA
no hard-coded URLs
retrieve a resource,
follow links
SO FAR

FROM HEAVEN
so close

to hell.
DOES SELF-DESCRIPTIVENESS
REDUCE COUPLING?
YES.
only the message itself

is needed for interpretation
“in-band”
DOES SELF-DESCRIPTIVENESS
REDUCE COUPLING?
NO.
REST APIs rely on media types.
“in-band”??
SO YOU UNDERSTAND JSON?
application/alto-costmap+json
application/alto-costmapfilter+json
application/alto-directory+json
...
DOES SELF-DESCRIPTIVENESS
REDUCE COUPLING?
Clients can interpret the message

using only in-band information…
…if they und...
DOES HYPERMEDIA
REDUCE COUPLING?
In each representation,
the server includes links
towards other resources.
DOES HYPERMEDIA
REDUCE COUPLING?
YES.
Clients don’t hard-code

a server’s URLs.
Clients don’t hard-code

the path to infor...
DOES HYPERMEDIA
REDUCE COUPLING?
In each representation,
the server includes links
towards other resources.
NO.
How can th...
DOES HYPERMEDIA
REDUCE COUPLING?
The server sends you an image.
Scale it.

Crop it.
But you want to do something else.
Bla...
HYPERMEDIA

cannot be the engine
media type coupling
affordance coupling
HYPERMEDIA

cannot be the engine
Hypermedia Heaven & Hell
Self-descriptive Salvation
Angels of Affordance
ENOUGH WITH THE

MEDIA TYPES ALREADY.
CHOOSE A SELF-DESCRIPTIVE

MEDIA TYPE.
JSON is just JSON.
“image” likely has

a hundred meanings.
CHOOSE A SELF-DESCRIPTIVE

MEDIA TYPE.
JSON-LD is self-descriptive.
“image” is actually a URL.
Clients can look it up.
CHOOSE A SELF-DESCRIPTIVE

MEDIA TYPE.
The client still has to

understand this media type.
But it’s not task-

or applica...
ADD SELF-DESCRIPTIVE

HYPERMEDIA CONTROLS.
<form>
<label>Person:</label>
<input name=“person” />
</form>
What does this do?
ADD SELF-DESCRIPTIVE

HYPERMEDIA CONTROLS.
Hydra
inside JSON-LD response
relate controls

to data properties
DESCRIBE THE

API BEFOREHAND.
in a hypermedia-based way
describe the links
(imageA) —B&W—> (imageB)
DESCRIBE THE

API BEFOREHAND.
in a resource-based way
describe the functionality
(imageA) ——> (imageB&W)
HYPERMEDIA

cannot be the engine
Hypermedia Heaven & Hell
Self-descriptive Salvation
Angels of Affordance
HYPERMEDIA RESPONSES SHOULD
AFFORD GOING TO NEXT STEPS.
Server: Here’s an image.
Client: Thanks. I want to scale it.
Serve...
HYPERMEDIA RESPONSES SHOULD
AFFORD GOING TO NEXT STEPS.
Client: Now use it as my

Facebook profile picture.
Server: Err…

...
IT’S HARD TO IMAGINE ALL WAYS

IN WHICH CLIENTS USE YOUR API.
IMPOSSIBLE
SELF-DESCRIPTIVENESS

GIVES THEM A CHOICE.
COMBINE SELF-DESCRIPTIVENESS

OF AN API’S RESPONSES…
…WITH SELF-DESCRIPTIVENESS

OF AN API’S FUNCTIONALITY
“This is a phot...
…TO COMPLETE THE INTERACTION

THAT HYPERMEDIA COULDN’T.
HYPERMEDIA
can be the engine
of a single API.
HYPERMEDIA
cannot the engine
of cross-API interactions.
BUILDING API
DESCRIPTIONS
is thinking about Web APIs
on a Web scale.
Upcoming SlideShare
Loading in...5
×

Hypermedia Cannot be the Engine

1,724

Published on

API Strategy & Practice
Amsterdam, 2014

Published in: Technology

Hypermedia Cannot be the Engine

  1. 1. HYPERMEDIA
 cannot be the engine HYPERMEDIA
 cannot be the engine Ruben Verborgh
 Ghent University – iMinds
  2. 2. “REST APIS MUST BE
 HYPERTEXT-DRIVEN.” Roy T. Fielding
  3. 3. HYPERMEDIA
 cannot be the engine Hypermedia Heaven & Hell Self-descriptive Salvation Angels of Affordance
  4. 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. 5. REST HAS
 A UNIFORM INTERFACE. resources representations self-descriptiveness hypermedia
  6. 6. RESOURCES identify resources, not actions resources are cacheable
  7. 7. REPRESENTATIONS share identifiers across systems different needs,
 different representations
  8. 8. SELF-DESCRIPTIVENESS no external documentation clients interpret representations
  9. 9. HYPERMEDIA no hard-coded URLs retrieve a resource, follow links
  10. 10. SO FAR
 FROM HEAVEN so close
 to hell.
  11. 11. DOES SELF-DESCRIPTIVENESS REDUCE COUPLING? YES. only the message itself
 is needed for interpretation “in-band”
  12. 12. DOES SELF-DESCRIPTIVENESS REDUCE COUPLING? NO. REST APIs rely on media types. “in-band”??
  13. 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. 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. 15. DOES HYPERMEDIA REDUCE COUPLING? In each representation, the server includes links towards other resources.
  16. 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. 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. 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. 19. HYPERMEDIA
 cannot be the engine media type coupling affordance coupling
  20. 20. HYPERMEDIA
 cannot be the engine Hypermedia Heaven & Hell Self-descriptive Salvation Angels of Affordance
  21. 21. ENOUGH WITH THE
 MEDIA TYPES ALREADY.
  22. 22. CHOOSE A SELF-DESCRIPTIVE
 MEDIA TYPE. JSON is just JSON. “image” likely has
 a hundred meanings.
  23. 23. CHOOSE A SELF-DESCRIPTIVE
 MEDIA TYPE. JSON-LD is self-descriptive. “image” is actually a URL. Clients can look it up.
  24. 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. 25. ADD SELF-DESCRIPTIVE
 HYPERMEDIA CONTROLS. <form> <label>Person:</label> <input name=“person” /> </form> What does this do?
  26. 26. ADD SELF-DESCRIPTIVE
 HYPERMEDIA CONTROLS. Hydra inside JSON-LD response relate controls
 to data properties
  27. 27. DESCRIBE THE
 API BEFOREHAND. in a hypermedia-based way describe the links (imageA) —B&W—> (imageB)
  28. 28. DESCRIBE THE
 API BEFOREHAND. in a resource-based way describe the functionality (imageA) ——> (imageB&W)
  29. 29. HYPERMEDIA
 cannot be the engine Hypermedia Heaven & Hell Self-descriptive Salvation Angels of Affordance
  30. 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. 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. 32. IT’S HARD TO IMAGINE ALL WAYS
 IN WHICH CLIENTS USE YOUR API. IMPOSSIBLE SELF-DESCRIPTIVENESS
 GIVES THEM A CHOICE.
  33. 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. 34. …TO COMPLETE THE INTERACTION
 THAT HYPERMEDIA COULDN’T.
  35. 35. HYPERMEDIA can be the engine of a single API. HYPERMEDIA cannot the engine of cross-API interactions.
  36. 36. BUILDING API DESCRIPTIONS is thinking about Web APIs on a Web scale.

×