Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
l All contents Copyright © 2014, MuleSoft Inc.
Hypermedia
The Good, the Bad, & the Ugly
by mike stowe
l All contents Copyright © 2014, MuleSoft Inc.
This talk isn’t designed to be a “here’s the
solution,” but rather to take ...
l All contents Copyright © 2014, MuleSoft Inc.
• API Fanatic
• Open Source Contributor
• Author, Speaker, Consultant
• 10+...
l All contents Copyright © 2014, MuleSoft Inc.4
Sometimes I feel that “over-engineering”
is this disease that is running w...
l All contents Copyright © 2014, MuleSoft Inc.
Hypermedia is nothing
new.
l All contents Copyright © 2014, MuleSoft Inc.
After all, hypertext has
been known to us since 1965
when defined by Ted Ne...
l All contents Copyright © 2014, MuleSoft Inc.
And goes back as far as 1945
when Vannevar Bush thought
of the concept in h...
l All contents Copyright © 2014, MuleSoft Inc.
But what exactly is
Hypermedia…
l All contents Copyright © 2014, MuleSoft Inc.
And how does it play into
RESTful APIs…
l All contents Copyright © 2014, MuleSoft Inc.10
a method of structuring information in
different media for a single user…...
l All contents Copyright © 2014, MuleSoft Inc.
Hypertext literally means
“beyond” text…
l All contents Copyright © 2014, MuleSoft Inc.12
A hypertext can be experienced in
countless different ways, and it allows...
l All contents Copyright © 2014, MuleSoft Inc.
In other words…
l All contents Copyright © 2014, MuleSoft Inc.14
Is text that is LINK driven, allowing
the client to control the flow and
...
l All contents Copyright © 2014, MuleSoft Inc.15
Hypertext is a computer-supported
medium for information in which many
in...
l All contents Copyright © 2014, MuleSoft Inc.
You might remember these
hypertext/media driven
applications
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
Or my personal favorite…
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
The challenge is that this
requires a hypertext/
hypermedia client, and an
...
l All contents Copyright © 2014, MuleSoft Inc.
The other challenge is
despite the need for a client
and interpreter, truly...
l All contents Copyright © 2014, MuleSoft Inc.24
What needs to be done to make the REST
architectural style clear on the n...
l All contents Copyright © 2014, MuleSoft Inc.
But before we go any further,
what is this HATEOAS?
l All contents Copyright © 2014, MuleSoft Inc.26
Representational State Transfer is made up of
six primary constraints:
• ...
l All contents Copyright © 2014, MuleSoft Inc.27
Hypermedia plays a role in:
•  Client/Server
•  Stateless
•  Cacheable
• ...
l All contents Copyright © 2014, MuleSoft Inc.28
Hypermedia plays a role in:
•  Client/Server
•  Stateless
•  Cacheable
• ...
l All contents Copyright © 2014, MuleSoft Inc.
Client/ Server
l All contents Copyright © 2014, MuleSoft Inc.
Stateless
l All contents Copyright © 2014, MuleSoft Inc.
Uniform Interface
l All contents Copyright © 2014, MuleSoft Inc.
Code on Demand
l All contents Copyright © 2014, MuleSoft Inc.
To recap – because REST is
STATELESS, it has to have a
way to REPRESENT sta...
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
To recap – hypermedia also
allows for independence
between the client and t...
l All contents Copyright © 2014, MuleSoft Inc.
However, true
implementation of REST and
hypermedia is still a work in
prog...
l All contents Copyright © 2014, MuleSoft Inc.
Current REST Hypermedia
Specs
l All contents Copyright © 2014, MuleSoft Inc.
Collection+JSON
l All contents Copyright © 2014, MuleSoft Inc.39
•  Created by Mike Amundsen in 2011
•  Based on Atom Publication/ Syndica...
l All contents Copyright © 2014, MuleSoft Inc.40
Collection+JSON
{	
  "collection"	
  :	
  
	
  	
  {	
  
	
  	
  	
  	
  ...
l All contents Copyright © 2014, MuleSoft Inc.41
Strengths:
•  Great for collections
•  Templated queries
•  Early wide ad...
l All contents Copyright © 2014, MuleSoft Inc.
JSON API
l All contents Copyright © 2014, MuleSoft Inc.43
•  Created by Steve Klabnik and Yahuda Klaz in
2013
•  Designed to ensure...
l All contents Copyright © 2014, MuleSoft Inc.44
JSON API
{	
  
	
  	
  "links":	
  {	
  
	
  	
  	
  	
  "posts.author":	...
l All contents Copyright © 2014, MuleSoft Inc.45
Strengths:
•  Simple, versatile format
•  Easy to read/ implement
•  Flat...
l All contents Copyright © 2014, MuleSoft Inc.
HAL
l All contents Copyright © 2014, MuleSoft Inc.47
•  Created by Mike Kelly in 2011
•  Allows for nesting of links
•  Suppor...
l All contents Copyright © 2014, MuleSoft Inc.48
HAL
{	
  
	
  	
  	
  	
  "_links":	
  {	
  
	
  	
  	
  	
  	
  	
  	
  ...
l All contents Copyright © 2014, MuleSoft Inc.49
Strengths:
•  Dynamic/ Nestable
•  Easy to read/ implement
•  Multi-forma...
l All contents Copyright © 2014, MuleSoft Inc.
HAL is also…
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
Not to be confused with…
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
JSON-LD
l All contents Copyright © 2014, MuleSoft Inc.55
•  Recognized as a W3C standard in 2014
•  Designed as a linking format
•...
l All contents Copyright © 2014, MuleSoft Inc.56
JSON-LD
{	
  
	
  	
  "@context":	
  "http://json-­‐ld.org/contexts/perso...
l All contents Copyright © 2014, MuleSoft Inc.57
Strengths:
•  Strong format for Data
Linking
•  Used across multiple
form...
l All contents Copyright © 2014, MuleSoft Inc.
I don’t have any funny
pictures for this one…
l All contents Copyright © 2014, MuleSoft Inc.
Siren
l All contents Copyright © 2014, MuleSoft Inc.60
•  Created by Kevin Swiber in 2012
•  Created specifically for Web APIs
•...
l All contents Copyright © 2014, MuleSoft Inc.61
Siren
{	
  
	
  	
  "class":	
  [	
  "order"	
  ],	
  
	
  	
  "propertie...
l All contents Copyright © 2014, MuleSoft Inc.62
Siren
	
  "actions":	
  [	
  
	
  	
  	
  	
  {	
  
	
  	
  	
  	
  	
  	...
l All contents Copyright © 2014, MuleSoft Inc.63
Strengths:
•  Provides a more verbose
spec
•  Query templating
•  Incorpo...
l All contents Copyright © 2014, MuleSoft Inc.
CPHL
l All contents Copyright © 2014, MuleSoft Inc.65
CPHL
•  Created by me in 2014
•  Considered a “brain storming” document
•...
l All contents Copyright © 2014, MuleSoft Inc.66
CPHL
Provides Strict Naming:
•  self: self provides a namespace for links...
l All contents Copyright © 2014, MuleSoft Inc.67
CPHL
{	
  	
  
	
  	
  	
  	
  "_definition":	
  {	
  	
  
	
  	
  	
  	
...
l All contents Copyright © 2014, MuleSoft Inc.68
CPHL
	
  "docHref":	
  "http://api.domain.com/docs/edit",	
  	
  
	
  	
 ...
l All contents Copyright © 2014, MuleSoft Inc.69
Strengths:
•  Cross-platform (XML,
JSON, YAML) architectural
consistency
...
l All contents Copyright © 2014, MuleSoft Inc.
Hypermedia Challenges
l All contents Copyright © 2014, MuleSoft Inc.
Nobody knows how to use
hypermedia…
l All contents Copyright © 2014, MuleSoft Inc.
Developers won’t utilize
hypermedia in their clients…
l All contents Copyright © 2014, MuleSoft Inc.
A good API shouldn’t
change…
l All contents Copyright © 2014, MuleSoft Inc.
Hypermedia doesn’t solve
versioning…
l All contents Copyright © 2014, MuleSoft Inc.
Hypermedia doesn’t replace
documentation…
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
Hypermedia destroys
resource location…
l All contents Copyright © 2014, MuleSoft Inc.
Hypermedia makes sense for
humans, but not machines…
l All contents Copyright © 2014, MuleSoft Inc.
Isn’t hypermedia just WSDL/
WADL?
l All contents Copyright © 2014, MuleSoft Inc.
We haven’t figured out a
good way to represent
hypermedia in APIs…
l All contents Copyright © 2014, MuleSoft Inc.
Hypermedia on the line
l All contents Copyright © 2014, MuleSoft Inc.
We have to remember we use
Hypermedia every single
day…
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
Webpages are rendered from
HTML - the Hypertext
Markup Language
l All contents Copyright © 2014, MuleSoft Inc.
Users are able to navigate
through “interfaces” at their
leisure and comman...
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
Challenges of HTML style
Hypermedia in APIs
l All contents Copyright © 2014, MuleSoft Inc.
The Yahoo HTML interface
requires human interaction,
and not all APIs want ...
l All contents Copyright © 2014, MuleSoft Inc.
A machine can follow the
links, but not necessarily
understand them…
l All contents Copyright © 2014, MuleSoft Inc.
HTML presents a visual
order, not a logical order…
l All contents Copyright © 2014, MuleSoft Inc.
The question is, what can we
learn from HTML, and what is
technologically p...
l All contents Copyright © 2014, MuleSoft Inc.
For example, HTML style
interfaces can provide
guidance towards API
hyperte...
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
/users	
  [get]	
  
/users/resetPassword	
  
/users	
  [post]	
  
/base	
  ...
l All contents Copyright © 2014, MuleSoft Inc.
HTML also has a standard
client and uniform format,
something that we do no...
l All contents Copyright © 2014, MuleSoft Inc.
In short, when compared to
HTML, REST Hypermedia
specs fall short… VERY
sho...
l All contents Copyright © 2014, MuleSoft Inc.
This is why new specs are
being created… on an
ongoing and regular basis
l All contents Copyright © 2014, MuleSoft Inc.
Yahapi
Uber Mason
CPHL
JSON API
HAL
JSON-LD
Collection+JSON Siren
l All contents Copyright © 2014, MuleSoft Inc.
And why companies like
PayPal and Vertical Response
have created their OWN
...
l All contents Copyright © 2014, MuleSoft Inc.102
PayPal’s Spec
"links"	
  :	
  [	
  
	
  	
  {	
  
	
  	
  	
  "href"	
  ...
l All contents Copyright © 2014, MuleSoft Inc.103
Vertical Response
"links":	
  {	
  
	
  	
  	
  	
  "up":	
  {	
  
	
  	...
l All contents Copyright © 2014, MuleSoft Inc.
It’s also what makes
integrating hypermedia into
your API so hard…
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
Future of API Hypermedia
l All contents Copyright © 2014, MuleSoft Inc.
You are the future!
Join the discussion:
Google Group – Hypermedia Web
l All contents Copyright © 2014, MuleSoft Inc.
Because we don’t have the
answer yet…
l All contents Copyright © 2014, MuleSoft Inc.
We need to think outside of
the box…
l All contents Copyright © 2014, MuleSoft Inc.
We need to think beyond
today…
l All contents Copyright © 2014, MuleSoft Inc.
But we also need to be
careful, keeping things
simple…
l All contents Copyright © 2014, MuleSoft Inc.
We need to remember
machines are getting
smarter….
l All contents Copyright © 2014, MuleSoft Inc.
Hypermedia interpreted by
Artificial Intelligence?
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
So then again…
l All contents Copyright © 2014, MuleSoft Inc.
l All contents Copyright © 2014, MuleSoft Inc.
Get the Book – and More! Sign up @
http://champions.mulesoft.com
l All contents Copyright © 2014, MuleSoft Inc.
@MuleDev
www.mulesoft.com
Upcoming SlideShare
Loading in …5
×

Hypermedia: The Good, the Bad, and the Ugly

6,712 views

Published on

Let's take a hard look at hypermedia, and what it really means to utilize HATEOAS (hypermedia as the engine of application state). We’re also going to jump into different hypertext specifications, tackle the hypermedia vs documentation debate, and take a good hard look at how hypermedia can help extend the life of your API. But we’re also going to take a hard look at the cons of implementing hypermedia, and why not everyone is a fan. In short, we want to look at the good, the bad, and the downright ugly to make sure that we utilize hypermedia in our RESTful APIs in the most efficient manner possible.

Notes to be added...

Published in: Software
  • Earn $500 for taking a 1 hour paid survey! read more... ➤➤ http://ishbv.com/surveys6/pdf
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Have you ever heard of taking paid surveys on the internet before? We have one right now that pays $50, and takes less than 10 minutes! If you want to take it, here is your personal link ◆◆◆ https://tinyurl.com/realmoneystreams2019
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • let's be honest. There are a lot of crazy devices, pumps and p.ills that all claim to be the solution to adding BIG length to your penis. However, most, if not all of these solutions don't pan out, or the growth is only temporary. I guess you could always consider surgery, but if you are anything like me, the thought of having a sharp metal object anywhere near your junk makes you quiver with blood curdling fear :-) Well, it just so happens my friend John, who I met at a men's health conference a few years back, has literally stumbled upon the key to natural male growth. Unlike other systems out there, his involves two unique components: 1. Restarting biological growth that boys experienced during puberty, turning them into men. 2. Performing tested and targeted exercises to encourage blood flow and supersize growth. John has just released a completely ZERO COST enlargement exercises guide where you can discover the proven techniques to start REAL and PERMANENT growth. Download the enlargement exercises guide here ▲▲▲ https://tinyurl.com/getpebible2019
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Do you want a longer and thicker penis without expensive surgery, extenders or suction devices that just don't work? Introducing the Penis Enlargement Bible, a 94 page downloadable e-book that has an exclusive two step system that can growth your penis by between 2 and 4 inches within 89 days using safe natural methods ●●● https://tinyurl.com/ydaetwbk
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Discover a WEIRD trick I use to make over $3500 per month taking paid surveys online. read more... ●●● http://ishbv.com/surveys6/pdf
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

Hypermedia: The Good, the Bad, and the Ugly

  1. 1. l All contents Copyright © 2014, MuleSoft Inc. Hypermedia The Good, the Bad, & the Ugly by mike stowe
  2. 2. l All contents Copyright © 2014, MuleSoft Inc. This talk isn’t designed to be a “here’s the solution,” but rather to take a look at where we’re at, and where we need to go. How to get there, is most likely, up to you. Disclaimer
  3. 3. l All contents Copyright © 2014, MuleSoft Inc. • API Fanatic • Open Source Contributor • Author, Speaker, Consultant • 10+ years hacking Professional Code • Dev Relations Manager at MuleSoft About Me Follow me on Twitter: @mikegstowe
  4. 4. l All contents Copyright © 2014, MuleSoft Inc.4 Sometimes I feel that “over-engineering” is this disease that is running wild in our industry and as architects we need to be on constant watch to quickly eliminate it whenever encountered. - Drew Jaegle
  5. 5. l All contents Copyright © 2014, MuleSoft Inc. Hypermedia is nothing new.
  6. 6. l All contents Copyright © 2014, MuleSoft Inc. After all, hypertext has been known to us since 1965 when defined by Ted Nelson
  7. 7. l All contents Copyright © 2014, MuleSoft Inc. And goes back as far as 1945 when Vannevar Bush thought of the concept in his article “As We May Think”
  8. 8. l All contents Copyright © 2014, MuleSoft Inc. But what exactly is Hypermedia…
  9. 9. l All contents Copyright © 2014, MuleSoft Inc. And how does it play into RESTful APIs…
  10. 10. l All contents Copyright © 2014, MuleSoft Inc.10 a method of structuring information in different media for a single user… whereby related items are connected in the same way as a hypertext. - Oxford English Dictionary Hypermedia is…
  11. 11. l All contents Copyright © 2014, MuleSoft Inc. Hypertext literally means “beyond” text…
  12. 12. l All contents Copyright © 2014, MuleSoft Inc.12 A hypertext can be experienced in countless different ways, and it allows the reader a level of control over his or her reading experience that isn’t possible with a conventional text. - Kara Schoonmaker, 2007 Hypertext
  13. 13. l All contents Copyright © 2014, MuleSoft Inc. In other words…
  14. 14. l All contents Copyright © 2014, MuleSoft Inc.14 Is text that is LINK driven, allowing the client to control the flow and make decisions on what actions to perform next Hypertext
  15. 15. l All contents Copyright © 2014, MuleSoft Inc.15 Hypertext is a computer-supported medium for information in which many interlinked documents are displayed with their links on a high-resolution computer screen. - Jeffrey Conklin Hypertext
  16. 16. l All contents Copyright © 2014, MuleSoft Inc. You might remember these hypertext/media driven applications
  17. 17. l All contents Copyright © 2014, MuleSoft Inc.
  18. 18. l All contents Copyright © 2014, MuleSoft Inc.
  19. 19. l All contents Copyright © 2014, MuleSoft Inc. Or my personal favorite…
  20. 20. l All contents Copyright © 2014, MuleSoft Inc.
  21. 21. l All contents Copyright © 2014, MuleSoft Inc.
  22. 22. l All contents Copyright © 2014, MuleSoft Inc. The challenge is that this requires a hypertext/ hypermedia client, and an interpreter to understand and choose the next action.
  23. 23. l All contents Copyright © 2014, MuleSoft Inc. The other challenge is despite the need for a client and interpreter, truly RESTful APIs must rely on hypermedia…
  24. 24. l All contents Copyright © 2014, MuleSoft Inc.24 What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed? - Dr. Roy Fielding
  25. 25. l All contents Copyright © 2014, MuleSoft Inc. But before we go any further, what is this HATEOAS?
  26. 26. l All contents Copyright © 2014, MuleSoft Inc.26 Representational State Transfer is made up of six primary constraints: •  Client/Server •  Stateless •  Cacheable •  Uniform Interface •  Layered System •  Code on Demand* REST
  27. 27. l All contents Copyright © 2014, MuleSoft Inc.27 Hypermedia plays a role in: •  Client/Server •  Stateless •  Cacheable •  Uniform Interface •  Layered System •  Code on Demand* REST + Hypermedia
  28. 28. l All contents Copyright © 2014, MuleSoft Inc.28 Hypermedia plays a role in: •  Client/Server •  Stateless •  Cacheable •  Uniform Interface •  Layered System •  Code on Demand* REST + Hypermedia
  29. 29. l All contents Copyright © 2014, MuleSoft Inc. Client/ Server
  30. 30. l All contents Copyright © 2014, MuleSoft Inc. Stateless
  31. 31. l All contents Copyright © 2014, MuleSoft Inc. Uniform Interface
  32. 32. l All contents Copyright © 2014, MuleSoft Inc. Code on Demand
  33. 33. l All contents Copyright © 2014, MuleSoft Inc. To recap – because REST is STATELESS, it has to have a way to REPRESENT state. That is the purpose of hypermedia, to act as the engine of state for the application.
  34. 34. l All contents Copyright © 2014, MuleSoft Inc.
  35. 35. l All contents Copyright © 2014, MuleSoft Inc. To recap – hypermedia also allows for independence between the client and the server, allows for a uniform interface, and can help with code on demand.
  36. 36. l All contents Copyright © 2014, MuleSoft Inc. However, true implementation of REST and hypermedia is still a work in progress…
  37. 37. l All contents Copyright © 2014, MuleSoft Inc. Current REST Hypermedia Specs
  38. 38. l All contents Copyright © 2014, MuleSoft Inc. Collection+JSON
  39. 39. l All contents Copyright © 2014, MuleSoft Inc.39 •  Created by Mike Amundsen in 2011 •  Based on Atom Publication/ Syndication Specs •  JSON and Collection based •  Used widely at one time •  Not as popular as JSON API/ HAL Collection+JSON
  40. 40. l All contents Copyright © 2014, MuleSoft Inc.40 Collection+JSON {  "collection"  :      {          "version"  :  "1.0",          "href"  :  "http://example.org/friends/",                    "links"  :  [              {"rel"  :  "feed",  "href"  :  "http://example.org/friends/rss"},              {"rel"  :  "queries",  "href"  :  "http://example.org/friends/?queries"},              {"rel"  :  "template",  "href"  :  "http://example.org/friends/?template"}          ],                    "items"  :  [              {                  "href"  :  "http://example.org/friends/jdoe",                  "data"  :  [                      {"name"  :  "full-­‐name",  "value"  :  "J.  Doe",  "prompt"  :  "Full  Name"},                      {"name"  :  "email",  "value"  :  "jdoe@example.org",  "prompt"  :  "Email"}                  ],                  "links"  :  [                      {"rel"  :  "blog",  "href"  :  "http://examples.org/blogs/jdoe",  "prompt"  :  "Blog"},                      {"rel"  :  "avatar",  "href"  :  "http://examples.org/images/jdoe",  "prompt"  :  "Avatar",  "render"  :   "image"}                  ]              }          ]      }     }  
  41. 41. l All contents Copyright © 2014, MuleSoft Inc.41 Strengths: •  Great for collections •  Templated queries •  Early wide adoption •  Recognized as a standard Collection+JSON Weaknesses: •  JSON only •  Lack of documentation identifier •  More complex for developers to implement
  42. 42. l All contents Copyright © 2014, MuleSoft Inc. JSON API
  43. 43. l All contents Copyright © 2014, MuleSoft Inc.43 •  Created by Steve Klabnik and Yahuda Klaz in 2013 •  Designed to ensure separation between client and server while also reducing the number of calls without impacting discoverability •  JSON based •  Not listed as stable •  One of the most popular specs JSON API
  44. 44. l All contents Copyright © 2014, MuleSoft Inc.44 JSON API {      "links":  {          "posts.author":  {              "href":  "http://example.com/people/{posts.author}",              "type":  "people"          },          "posts.comments":  {              "href":  "http://example.com/comments/{posts.comments}",              "type":  "comments"          }      },      "posts":  [{          "id":  "1",          "title":  "Rails  is  Omakase",          "links":  {              "author":  "9",              "comments":  [  "5",  "12",  "17",  "20"  ]          }      }]   }  
  45. 45. l All contents Copyright © 2014, MuleSoft Inc.45 Strengths: •  Simple, versatile format •  Easy to read/ implement •  Flat link grouping •  URI templating •  Wide adoption •  Strong community •  Recognized as a Hypermedia standard JSON API Weaknesses: •  JSON only •  Lack of documentation identifier •  Slightly more difficult for clients to interpret •  Still considered a work in progress
  46. 46. l All contents Copyright © 2014, MuleSoft Inc. HAL
  47. 47. l All contents Copyright © 2014, MuleSoft Inc.47 •  Created by Mike Kelly in 2011 •  Allows for nesting of links •  Supports JSON and XML •  Incorporates documentation •  One of the most popular specs HAL
  48. 48. l All contents Copyright © 2014, MuleSoft Inc.48 HAL {          "_links":  {                  "self":  {  "href":  "/orders"  },                  "curies":  [{  "name":  "ea",  "href":  "http://example.com/docs/ rels/{rel}",  "templated":  true  }],                  "next":  {  "href":  "/orders?page=2"  },                  "ea:find":  {                          "href":  "/orders{?id}",                          "templated":  true                  },                  "ea:admin":  [{                          "href":  "/admins/2",                          "title":  "Fred"                  },  {                          "href":  "/admins/5",                          "title":  "Kate"                  }]          },   }  
  49. 49. l All contents Copyright © 2014, MuleSoft Inc.49 Strengths: •  Dynamic/ Nestable •  Easy to read/ implement •  Multi-format (JSON/XML) •  URI Templating •  Inclusion of documentation •  Wide adoption •  Strong Community •  RFC proposed/ recognized spec HAL Weaknesses: •  JSON/XML formats architecturally different •  CURIES (documentation) are tightly coupled
  50. 50. l All contents Copyright © 2014, MuleSoft Inc. HAL is also…
  51. 51. l All contents Copyright © 2014, MuleSoft Inc.
  52. 52. l All contents Copyright © 2014, MuleSoft Inc. Not to be confused with…
  53. 53. l All contents Copyright © 2014, MuleSoft Inc.
  54. 54. l All contents Copyright © 2014, MuleSoft Inc. JSON-LD
  55. 55. l All contents Copyright © 2014, MuleSoft Inc.55 •  Recognized as a W3C standard in 2014 •  Designed as a linking format •  Can be used for both APIs and NoSQL •  Less popular than JSON API / HAL •  Very active community JSON-LD
  56. 56. l All contents Copyright © 2014, MuleSoft Inc.56 JSON-LD {      "@context":  "http://json-­‐ld.org/contexts/person.jsonld",      "@id":  "http://dbpedia.org/resource/John_Lennon",      "name":  "John  Lennon",      "born":  "1940-­‐10-­‐09",      "spouse":  "http://dbpedia.org/resource/Cynthia_Lennon"   }  
  57. 57. l All contents Copyright © 2014, MuleSoft Inc.57 Strengths: •  Strong format for Data Linking •  Used across multiple formats •  Strong community •  Large working group •  W3C standard JSON-LD Weaknesses: •  JSON only •  More complex to integrate/ interpret •  No identifier for documentation
  58. 58. l All contents Copyright © 2014, MuleSoft Inc. I don’t have any funny pictures for this one…
  59. 59. l All contents Copyright © 2014, MuleSoft Inc. Siren
  60. 60. l All contents Copyright © 2014, MuleSoft Inc.60 •  Created by Kevin Swiber in 2012 •  Created specifically for Web APIs •  Presents information on classes, entities, actions, and links •  Incorporates methods •  Supports JSON and XML •  Not as popular as JSON API and HAL •  Still a work in progress Siren
  61. 61. l All contents Copyright © 2014, MuleSoft Inc.61 Siren {      "class":  [  "order"  ],      "properties":  {                "orderNumber":  42,                "itemCount":  3,              "status":  "pending"      },      "entities":  [          {                "class":  [  "items",  "collection"  ],                "rel":  [  "http://x.io/rels/order-­‐items"  ],                "href":  "http://api.x.io/orders/42/items"          },          {              "class":  [  "info",  "customer"  ],              "rel":  [  "http://x.io/rels/customer"  ],                "properties":  {                    "customerId":  "pj123",                  "name":  "Peter  Joseph"              },              "links":  [                  {  "rel":  [  "self"  ],  "href":  "http://api.x.io/customers/pj123"  }              ]          }      ],      
  62. 62. l All contents Copyright © 2014, MuleSoft Inc.62 Siren  "actions":  [          {              "name":  "add-­‐item",              "title":  "Add  Item",              "method":  "POST",              "href":  "http://api.x.io/orders/42/items",              "type":  "application/x-­‐www-­‐form-­‐urlencoded",              "fields":  [                  {  "name":  "orderNumber",  "type":  "hidden",  "value":  "42"  },                  {  "name":  "productCode",  "type":  "text"  },                  {  "name":  "quantity",  "type":  "number"  }              ]          }      ],      "links":  [          {  "rel":  [  "self"  ],  "href":  "http://api.x.io/orders/42"  },          {  "rel":  [  "previous"  ],  "href":  "http://api.x.io/orders/41"  },          {  "rel":  [  "next"  ],  "href":  "http://api.x.io/orders/43"  }      ]   }  
  63. 63. l All contents Copyright © 2014, MuleSoft Inc.63 Strengths: •  Provides a more verbose spec •  Query templating •  Incorporates Actions •  Multi-format** Siren Weaknesses: •  Poor adoption •  Lacks documentation •  Work in progress
  64. 64. l All contents Copyright © 2014, MuleSoft Inc. CPHL
  65. 65. l All contents Copyright © 2014, MuleSoft Inc.65 CPHL •  Created by me in 2014 •  Considered a “brain storming” document •  Multi-format with architectural consistency •  Action driven verses Resource driven •  Incorporates API definition specs (RAML/ Swagger) •  Allows for documentation and Code on Demand •  Not widely adopted or used •  Not considered stable
  66. 66. l All contents Copyright © 2014, MuleSoft Inc.66 CPHL Provides Strict Naming: •  self: self provides a namespace for links to docs and code related to the exact call the client is on •  create: Create a new record via the POST method (equivalent to self::POST) •  read: retrieve an item or collection via GET (equivalent to self::GET) •  update: utilization of the put/ patch methods to update an item, or all items in a collection* (self::PUT) •  delete: deletes the item or the collection* (equivalent to self::DELETE) •  search: the resource to perform a search on a collection •  first: links to the first record in a collection •  beginning: links to the first set of records in a paginated result •  prev: links to the previous set of records in a paginated result •  next: links to the next set of records in a paginated result •  last: links to the last record of a paginated result •  end: links to the last set of records in a paginated result •  base: links back to the starting point of a hypermedia API
  67. 67. l All contents Copyright © 2014, MuleSoft Inc.67 CPHL {            "_definition":  {                    "raml":  "http://api.domain.com/docs/api/raml",                    "swagger":  "http://api.domain.com/docs/api/swagger"            },            "_links":  {                    "update":  {                            "title":  "Edit  User",                            "description":  "edit  the  user",                            "href":  "/api/resource",                            "methods":  [                                    "put",                                    "patch"                            ],                            "formats":  {                                    "json":  {                                            "mimeType":  "application/json",                                            "schema":  "http://api.domain.com/docs/api/editSchema.json"                                    },                                    "xml":  {                                            "mimeType":  "text/xml",                                            "schema":  "http://api.domain.com/docs/api/editSchema.xml"                                    }                            },    
  68. 68. l All contents Copyright © 2014, MuleSoft Inc.68 CPHL  "docHref":  "http://api.domain.com/docs/edit",                            "code":  {                                    "php":  {                                            "href":  "http://code.domain.com/phplib/edit.tgz",                                            "md5":  "0cc175b9c0f1b6a831c399e269772661",                                            "recordSpecific":  false                                    },                                    "java":  {                                            "href":  "http://code.domain.com/javalib/edit.tgz",                                            "md5":  "0cc175b9c0f1b6a831c399e269772661",                                            "recordSpecific":  false                                    },                                    "ruby":  {                                            "href":  "http://code.domain.com/rubylib/edit.tgz",                                            "md5":  "0cc175b9c0f1b6a831c399e269772661",                                            "recordSpecific":  false                                    }                            }                    }            }     }  
  69. 69. l All contents Copyright © 2014, MuleSoft Inc.69 Strengths: •  Cross-platform (XML, JSON, YAML) architectural consistency •  Incorporates documentation, methods, and code on demand •  Provides strict name templating for common actions CPHL Weaknesses: •  Poor adoption •  Not heavily tested/ supported •  Can become bloated/ overly verbose •  Not stable – brain storming document
  70. 70. l All contents Copyright © 2014, MuleSoft Inc. Hypermedia Challenges
  71. 71. l All contents Copyright © 2014, MuleSoft Inc. Nobody knows how to use hypermedia…
  72. 72. l All contents Copyright © 2014, MuleSoft Inc. Developers won’t utilize hypermedia in their clients…
  73. 73. l All contents Copyright © 2014, MuleSoft Inc. A good API shouldn’t change…
  74. 74. l All contents Copyright © 2014, MuleSoft Inc. Hypermedia doesn’t solve versioning…
  75. 75. l All contents Copyright © 2014, MuleSoft Inc. Hypermedia doesn’t replace documentation…
  76. 76. l All contents Copyright © 2014, MuleSoft Inc.
  77. 77. l All contents Copyright © 2014, MuleSoft Inc. Hypermedia destroys resource location…
  78. 78. l All contents Copyright © 2014, MuleSoft Inc. Hypermedia makes sense for humans, but not machines…
  79. 79. l All contents Copyright © 2014, MuleSoft Inc. Isn’t hypermedia just WSDL/ WADL?
  80. 80. l All contents Copyright © 2014, MuleSoft Inc. We haven’t figured out a good way to represent hypermedia in APIs…
  81. 81. l All contents Copyright © 2014, MuleSoft Inc. Hypermedia on the line
  82. 82. l All contents Copyright © 2014, MuleSoft Inc. We have to remember we use Hypermedia every single day…
  83. 83. l All contents Copyright © 2014, MuleSoft Inc.
  84. 84. l All contents Copyright © 2014, MuleSoft Inc. Webpages are rendered from HTML - the Hypertext Markup Language
  85. 85. l All contents Copyright © 2014, MuleSoft Inc. Users are able to navigate through “interfaces” at their leisure and command:
  86. 86. l All contents Copyright © 2014, MuleSoft Inc.
  87. 87. l All contents Copyright © 2014, MuleSoft Inc.
  88. 88. l All contents Copyright © 2014, MuleSoft Inc.
  89. 89. l All contents Copyright © 2014, MuleSoft Inc. Challenges of HTML style Hypermedia in APIs
  90. 90. l All contents Copyright © 2014, MuleSoft Inc. The Yahoo HTML interface requires human interaction, and not all APIs want to require this…
  91. 91. l All contents Copyright © 2014, MuleSoft Inc. A machine can follow the links, but not necessarily understand them…
  92. 92. l All contents Copyright © 2014, MuleSoft Inc. HTML presents a visual order, not a logical order…
  93. 93. l All contents Copyright © 2014, MuleSoft Inc. The question is, what can we learn from HTML, and what is technologically possible?
  94. 94. l All contents Copyright © 2014, MuleSoft Inc. For example, HTML style interfaces can provide guidance towards API hypertext linking:
  95. 95. l All contents Copyright © 2014, MuleSoft Inc.
  96. 96. l All contents Copyright © 2014, MuleSoft Inc. /users  [get]   /users/resetPassword   /users  [post]   /base  [get]  
  97. 97. l All contents Copyright © 2014, MuleSoft Inc. HTML also has a standard client and uniform format, something that we do not currently have for APIs…
  98. 98. l All contents Copyright © 2014, MuleSoft Inc. In short, when compared to HTML, REST Hypermedia specs fall short… VERY short.
  99. 99. l All contents Copyright © 2014, MuleSoft Inc. This is why new specs are being created… on an ongoing and regular basis
  100. 100. l All contents Copyright © 2014, MuleSoft Inc. Yahapi Uber Mason CPHL JSON API HAL JSON-LD Collection+JSON Siren
  101. 101. l All contents Copyright © 2014, MuleSoft Inc. And why companies like PayPal and Vertical Response have created their OWN specs
  102. 102. l All contents Copyright © 2014, MuleSoft Inc.102 PayPal’s Spec "links"  :  [      {        "href"  :  "https://api.sandbox.paypal.com/v1/payments/ payment/PAY-­‐2XR800907F429382MKEBWOSA",        "rel"  :  "self",        "method"  :  "GET"      },  {        "href"  :  "https://api.sandbox.paypal.com/v1/payments/ payment/PAY-­‐2XR800907F429382MKEBWOSA/execute",        "rel"  :  "update",        "method"  :  "POST"      }   ]  
  103. 103. l All contents Copyright © 2014, MuleSoft Inc.103 Vertical Response "links":  {          "up":  {                  "url":  "https://vrapi.verticalresponse.com/api/v1/contacts"          },          "lists":  {                  "url":  "https://vrapi.verticalresponse.com/api/v1/contacts/ 1099513934863/lists"          },          "messages":  {                  "url":  "https://vrapi.verticalresponse.com/api/v1/contacts/ 1099513934863/messages"          },          "stats":  {                  "url":  "https://vrapi.verticalresponse.com/api/v1/contacts/ 1099513934863/stats"          }   }  
  104. 104. l All contents Copyright © 2014, MuleSoft Inc. It’s also what makes integrating hypermedia into your API so hard…
  105. 105. l All contents Copyright © 2014, MuleSoft Inc.
  106. 106. l All contents Copyright © 2014, MuleSoft Inc. Future of API Hypermedia
  107. 107. l All contents Copyright © 2014, MuleSoft Inc. You are the future! Join the discussion: Google Group – Hypermedia Web
  108. 108. l All contents Copyright © 2014, MuleSoft Inc. Because we don’t have the answer yet…
  109. 109. l All contents Copyright © 2014, MuleSoft Inc. We need to think outside of the box…
  110. 110. l All contents Copyright © 2014, MuleSoft Inc. We need to think beyond today…
  111. 111. l All contents Copyright © 2014, MuleSoft Inc. But we also need to be careful, keeping things simple…
  112. 112. l All contents Copyright © 2014, MuleSoft Inc. We need to remember machines are getting smarter….
  113. 113. l All contents Copyright © 2014, MuleSoft Inc. Hypermedia interpreted by Artificial Intelligence?
  114. 114. l All contents Copyright © 2014, MuleSoft Inc.
  115. 115. l All contents Copyright © 2014, MuleSoft Inc.
  116. 116. l All contents Copyright © 2014, MuleSoft Inc.
  117. 117. l All contents Copyright © 2014, MuleSoft Inc. So then again…
  118. 118. l All contents Copyright © 2014, MuleSoft Inc.
  119. 119. l All contents Copyright © 2014, MuleSoft Inc. Get the Book – and More! Sign up @ http://champions.mulesoft.com
  120. 120. l All contents Copyright © 2014, MuleSoft Inc. @MuleDev www.mulesoft.com

×