HATEOAS 101An Opinionated IntroductionBrian Mulloy                   Apigee@landlessness                 @apigee
groups.google.com/group/api-craft
youtube.com/apigee
New!       IRC Channel         #api-craft        on freenode
WARNING: The author may betray a bias againstthe application of REST constraints to web APIs.
What is HATEOAS?
Hypermedia As The Engine Of Application State
Let’s put HATEOAS in the full context of REST.
The Constraints of REST1.   Client-server2.   Stateless server3.   Cache4.   Uniform interface     a.   Identification of ...
Let’s break it down.
The first three constraints…
1. Client-server2. Stateless server3. Cache
…give us the client-cache-stateless-server web architecture.
clientcache          Each request          must contain         all information.     No stored                            ...
(we’ll come back to the 4th constraint)
The 5th constraint, Layered System, lets us addfeatures like a gateway, load balancer and firewall.
Each layer                       Layers can encapsulateprovides services                   legacy services & protect      ...
The optional 6th constraint, Code-on-Demand, allows theclient to request code from the server & execute it.
Add features to a          deployed client, which          provides for improved             extensibility and            ...
Now lets tackle the 4 parts of the 4th constraint,Uniform Interface
With help from the Twitter UI.
a. Resource Identifier identifies the particular resourceinvolved in an interaction between components.
http://twitter.com/#!/jack/status/20
b. Resource Representation represents the state of aresource for transfer between components.
<!DOCTYPE html><html data-nav-highlight-class-name="highlight-global-nav-home">  <head>    <title>Twitter</title><meta htt...
c. Self-descriptive messages contains all the informationnecessary to complete transformations.
GET /#!/jack/status/20 HTTP/1.1User-Agent: Chrome/18.0.1025.11Host: twitter.comAccept: text/html
d. Hypermedia as the engine of application state
state                                     state        transition           transition                     state        tr...
“   The name „Representational State Transfer‟ is intended    to evoke an image of how a well-designed Web    application ...
States are web pages.
Transitions are hyperlinks.
The key to implementing HATEOAS is pretty simple
In each response message include the links for the nextrequest message.
REST InterfaceApp    Browser                                  App                                  UI ServerUser     App  ...
home                   connect        discover     search                my profile           direct messages             ...
1 transition in, 32 transitions out
A quick aside
The three greatest inventions of all time are:
Bicycles
Beer
The Hyperlink
With a browser I can start at http://twitter.com
And navigate my way through every state of the entireTwitter application.
It’s amazing!
HATEOAS is not scary.
HATEOAS is the key constraint that makes surfing theweb with a browser possible.
Let’s look at HATEOAS and APIs
With help from the Twitter API.
GET /1/statuses/show/20.jsonHTTP/1.1Host: api.twitter.com
{    "created_at": "Tue Mar 21 20:50:14 +0000 2006",    "id": 20,    "id_str": "20",     "text": "just setting up my twttr...
Uh oh. There are zero hyperlinks.
How many should there be to respect the HATEOASconstraint?
At least one.
{    "created_at": "Tue Mar 21 20:50:14 +0000 2006",    "id": 20,    "id_str": "20",     "text": "just setting up my twttr...
A few questions.
Now are we HATEOAS compliant?
If we add another link does it change the consumingapplication’s state machine?
Is it ok for the developer to ignore included links?
Can the developer add out-of-band links to her app?
What happens when an app relies on multiple APIs?Where is the state machine?
If the Twitter API had complied with HATEOAS
When Loren Brichter
Created Tweetie
Would he have been able to decide which user actions toinclude in his design?
Or would those decisions have been driven by the links inthe response from the Twitter API?
Nearly all popular web UIs adhere to HATEOAS.
Nearly all popular web APIs violate HATEOAS.
Why?
Let’s examine the two worlds.
I guarantee                             hypermedia is                             engine of appI decide where             ...
The person who crafts the experience (state diagram)and the app user have the REST interface between them.
And the hypermedia links are given directly to the appuser at runtime.
So the hypermedia in each response message isgenuinely the engine of application state.
This pattern is not limited to user interfaces.
We see the same pattern for syndication feeds.
I guarantee                                hypermedia is                                engine of app                     ...
But the world of apps and web APIs seems different.
Interface                  App       App 1               Developer 1App                                      API Server   ...
Interface                  I craft the user experience,                                                                   ...
The person who crafts the experience (state machine)and the app user do not have the REST interfacebetween them.
And the hypermedia links are not given directly to theapp user at runtime.
Instead, the hypermedia are given to the developer atdesign time.
And the developer decides which states are possible forthe app user at runtime.
We need a Yoda moment.
“ You must unlearn what you have learned.                                            -Yoda
I used to call the world of popular, non-HATEOAS, non-SOAP web APIs, Pragmatic REST.
Oops.
How do we answer the questions many API teams areasking
1. Should we go down the HATEOAS path?
As a practical matter, for many teams that previousquestion is the same as the next question.
2. Should we include links in our responses?
But they have different answers.
1. For an API to be HATEOAS-compliant it requires aclient app that is also HATEOAS-compliant.
A user-interface app driven by web APIs would be akin toa feed reader for syndicated content.
But designed to handle generic web APIs.
I guarantee                            hypermedia is                            engine of appI decide where               ...
Special thanks to @elasticpath for this metaphor.
There are interesting non-UI applications as well.
“   However, the style does not assume that all applications    are browsers. In fact, the application details are hidden ...
If you’re not going down the HATEOAS client path, shouldyou include links anyway?
2. If you think including links in the API response will behelpful for developers at design time, then go for it.
But I wouldn’t call it HATEOAS because those links areprobably not the engine of application state for the appuser at run ...
“   If the engine of application state (and hence the    API) is not being driven by hypertext, then it    cannot be RESTf...
Here’s a call to action
We know what REST with the HATEOAS constraintis and isn’t.
We know what SOAP is and isn’t.
But we don’t have an intellectual framework forthe way so many popular apps and web APIs worktoday.
We need a really smart person
Who cares about web APIs
To examine the constraints of REST
The Constraints of REST1.   Client-server2.   Stateless server3.   Cache4.   Uniform interface     a.   Identification of ...
While keeping in mind how custom apps are builtby people using web APIs
Interface                  App       App 1               Developer 1App                                      API Server   ...
To give us a new foundation
The Constraints of ____1.   ???2.   ???3.   ???4.   ???5.   ???6.   ???
So that we will have a better shared idea of whatwe’re really doing
We will be able to communicate more effectively
And we will be able to create more value for theplanet and the people on it.
But please choose a nice, pronounceable acronym.
Further Exploring• http://steveklabnik.com/• http://pinboard.in/u:earth2marsh/t:hateoas/• http://www.ics.uci.edu/~fielding...
Questions?
THANK YOUSubscribe to API webinars at:youtube.com/apigee
THANK YOUIRC#api-crafton freenode
THANK YOUQuestions and ideas to:groups.google.com/group/api-craft
THANK YOUContact me at:@landlessnessbrian@apigee.com
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
HATEOAS 101 - Opinionated Introduction to a REST API Style
Prochain SlideShare
Chargement dans…5
×

HATEOAS 101 - Opinionated Introduction to a REST API Style

112 771 vues

Publié le

WARNING: This will be an opinionated webinar.
Among Web architects and API designers we've seen growing interest in HATEOAS as a valuable approach to RESTful Web APIs. In this Webinar, we'll introduce the core principles, look at examples, and explore the value of the approach for API providers and application developers.
Join this live Webinar with Brian Mulloy to discuss the fundamentals and to explore the trade-offs of providing and consuming HATEOAS APIs.
If you can't join the live webinar, register and we'll send you a video recording.
We Will Discuss »
Overview of HATEOAS
Example Applications
Pros and cons of using HATEOS for RESTful API design

Publié dans : Technologie
8 commentaires
104 j’aime
Statistiques
Remarques
Aucun téléchargement
Vues
Nombre de vues
112 771
Sur SlideShare
0
Issues des intégrations
0
Intégrations
66 712
Actions
Partages
0
Téléchargements
687
Commentaires
8
J’aime
104
Intégrations 0
Aucune incorporation

Aucune remarque pour cette diapositive
  • Creative Commons Attribution-Share Alike 3.0 United States License
  • http://www.flickr.com/photos/kmakice/2478522449/
  • http://www.flickr.com/photos/kmakice/2478522449/
  • HATEOAS 101 - Opinionated Introduction to a REST API Style

    1. 1. HATEOAS 101An Opinionated IntroductionBrian Mulloy Apigee@landlessness @apigee
    2. 2. groups.google.com/group/api-craft
    3. 3. youtube.com/apigee
    4. 4. New! IRC Channel #api-craft on freenode
    5. 5. WARNING: The author may betray a bias againstthe application of REST constraints to web APIs.
    6. 6. What is HATEOAS?
    7. 7. Hypermedia As The Engine Of Application State
    8. 8. Let’s put HATEOAS in the full context of REST.
    9. 9. The Constraints of REST1. Client-server2. Stateless server3. Cache4. Uniform interface a. Identification of resources b. Manipulation of resources through representations c. Self-descriptive messages d. Hypermedia as the engine of application state5. Layered System6. Code-On-Demand (optional)
    10. 10. Let’s break it down.
    11. 11. The first three constraints…
    12. 12. 1. Client-server2. Stateless server3. Cache
    13. 13. …give us the client-cache-stateless-server web architecture.
    14. 14. clientcache Each request must contain all information. No stored context on the stateless server. server Client has the right to reuseclient response data.cache
    15. 15. (we’ll come back to the 4th constraint)
    16. 16. The 5th constraint, Layered System, lets us addfeatures like a gateway, load balancer and firewall.
    17. 17. Each layer Layers can encapsulateprovides services legacy services & protect new services from legacy statelessto it’s neighbors. clients. server load stateless client firewall gateway balancer server Each layer cannot stateless "see" beyond it’s server immediate neighbor.
    18. 18. The optional 6th constraint, Code-on-Demand, allows theclient to request code from the server & execute it.
    19. 19. Add features to a deployed client, which provides for improved extensibility and configurabilityclient stateless servercode Better user-perceived performance and efficiency
    20. 20. Now lets tackle the 4 parts of the 4th constraint,Uniform Interface
    21. 21. With help from the Twitter UI.
    22. 22. a. Resource Identifier identifies the particular resourceinvolved in an interaction between components.
    23. 23. http://twitter.com/#!/jack/status/20
    24. 24. b. Resource Representation represents the state of aresource for transfer between components.
    25. 25. <!DOCTYPE html><html data-nav-highlight-class-name="highlight-global-nav-home"> <head> <title>Twitter</title><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta charset="utf-8" /> <meta name="description" content="Instantly connect to what's most important toyou. Follow your friends, experts, favorite celebrities, and breaking news." /> <link rel="dns-prefetch" href="http://a0.twimg.com"/> <link rel="dns-prefetch" href="http://api.twitter.com"/><script type="text/javascript" charset="utf-8"> document.domain = twitter.com; // this will be copied to twttr.appStartTime once our JS has started up document.startTime = new Date().getTime(); var twttr = {}; twttr.versionName = phoenix; twttr.isT1 = true; twttr.didPingKeynote = false; twttr.keynoteTTFTPing = function() { if (!twttr.didPingKeynote && window.location.href.indexOf(keynoteTest) > 0) { var image = document.createElement(img); image.src = /images/keynote.gif; twttr.didPingKeynote = true; } } window.console||function(){vara=["log","debug","info","warn","error","assert","dir","dirxml","group","groupEnd","time","timeEnd","count","trace","profile","profileEnd"];window.console={};for(varb=0;b<a.length;++b)window.console[a[b]]=function(){}}();</script>…
    26. 26. c. Self-descriptive messages contains all the informationnecessary to complete transformations.
    27. 27. GET /#!/jack/status/20 HTTP/1.1User-Agent: Chrome/18.0.1025.11Host: twitter.comAccept: text/html
    28. 28. d. Hypermedia as the engine of application state
    29. 29. state state transition transition state transition transitionstate state
    30. 30. “ The name „Representational State Transfer‟ is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through the application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use. -Roy Fielding Architectural Styles and the Design of Network-based Software Architectures Chapter 6
    31. 31. States are web pages.
    32. 32. Transitions are hyperlinks.
    33. 33. The key to implementing HATEOAS is pretty simple
    34. 34. In each response message include the links for the nextrequest message.
    35. 35. REST InterfaceApp Browser App UI ServerUser App Developer
    36. 36. home connect discover search my profile direct messages google: lists jack‟s first favorite about tweet help retweet reply to keyboard @jack shortcuts turn off retweets settings report @jack for spam sign out add or removeblock @jack tweet to @jack Follow @jack @jack new tweet from lists
    37. 37. 1 transition in, 32 transitions out
    38. 38. A quick aside
    39. 39. The three greatest inventions of all time are:
    40. 40. Bicycles
    41. 41. Beer
    42. 42. The Hyperlink
    43. 43. With a browser I can start at http://twitter.com
    44. 44. And navigate my way through every state of the entireTwitter application.
    45. 45. It’s amazing!
    46. 46. HATEOAS is not scary.
    47. 47. HATEOAS is the key constraint that makes surfing theweb with a browser possible.
    48. 48. Let’s look at HATEOAS and APIs
    49. 49. With help from the Twitter API.
    50. 50. GET /1/statuses/show/20.jsonHTTP/1.1Host: api.twitter.com
    51. 51. { "created_at": "Tue Mar 21 20:50:14 +0000 2006", "id": 20, "id_str": "20", "text": "just setting up my twttr", "source": "web", "truncated": false, "in_reply_to_status_id": null, "in_reply_to_status_id_str": null, "in_reply_to_user_id": null, "in_reply_to_user_id_str": null, "in_reply_to_screen_name": null, "user": { "id": 12, "id_str": "12", "name": "Jack Dorsey", "screen_name": "jack", "location": "San Francisco", "description": "Executive Chairman of Twitter, CEO of Square, a founder of both.", "url": null, "protected": false, "followers_count": 1935426, "friends_count": 1148, "listed_count": 17312, "created_at": "Tue Mar 21 20:50:14 +0000 2006", "favourites_count": 988, "utc_offset": -28800, "time_zone": "Pacific Time (US & Canada)", "geo_enabled": true, "verified": true, "statuses_count": 10894, "lang": "en", "contributors_enabled": true, "is_translator": false, "profile_background_color": "EBEBEB", "profile_background_image_url": "http://a0.twimg.com/images/themes/theme7/bg.gif", "profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme7/bg.gif", "profile_background_tile": false, "profile_image_url": "http://a0.twimg.com/profile_images/1563216547/image_normal.jpg", "profile_image_url_https": "https://si0.twimg.com/profile_images/1563216547/image_normal.jpg", "profile_link_color": "990000", "profile_sidebar_border_color": "DFDFDF", "profile_sidebar_fill_color": "F3F3F3", "profile_text_color": "333333", "profile_use_background_image": true, "show_all_inline_media": true, "default_profile": false, "default_profile_image": false, "following": null, "follow_request_sent": null, "notifications": null }, "geo": null, "coordinates": null, "place": null, "contributors": null, "retweet_count": 5973, "favorited": false, "retweeted": false}
    52. 52. Uh oh. There are zero hyperlinks.
    53. 53. How many should there be to respect the HATEOASconstraint?
    54. 54. At least one.
    55. 55. { "created_at": "Tue Mar 21 20:50:14 +0000 2006", "id": 20, "id_str": "20", "text": "just setting up my twttr", "source": "web", "truncated": false, "in_reply_to_status_id": null, "in_reply_to_status_id_str": null, "in_reply_to_user_id": null, "in_reply_to_user_id_str": null, "in_reply_to_screen_name": null, "user": { "id": 12, "link": ”http://api.twitter.com/1/users/show.json?user_id=12", "id_str": "12", "name": "Jack Dorsey", "screen_name": "jack", "location": "San Francisco", "description": "Executive Chairman of Twitter, CEO of Square, a founder of both.", "url": null, "protected": false, "followers_count": 1935426, "friends_count": 1148, "listed_count": 17312, "created_at": "Tue Mar 21 20:50:14 +0000 2006", "favourites_count": 988, "utc_offset": -28800, "time_zone": "Pacific Time (US & Canada)", "geo_enabled": true, "verified": true, "statuses_count": 10894, "lang": "en", "contributors_enabled": true, "is_translator": false, "profile_background_color": "EBEBEB", "profile_background_image_url": "http://a0.twimg.com/images/themes/theme7/bg.gif", "profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme7/bg.gif", "profile_background_tile": false, "profile_image_url": "http://a0.twimg.com/profile_images/1563216547/image_normal.jpg", "profile_image_url_https": "https://si0.twimg.com/profile_images/1563216547/image_normal.jpg", "profile_link_color": "990000", "profile_sidebar_border_color": "DFDFDF", "profile_sidebar_fill_color": "F3F3F3", "profile_text_color": "333333", "profile_use_background_image": true, "show_all_inline_media": true, "default_profile": false, "default_profile_image": false, "following": null, "follow_request_sent": null, "notifications": null }, "geo": null, "coordinates": null, "place": null, "contributors": null, "retweet_count": 5973, "favorited": false, "retweeted": false}
    56. 56. A few questions.
    57. 57. Now are we HATEOAS compliant?
    58. 58. If we add another link does it change the consumingapplication’s state machine?
    59. 59. Is it ok for the developer to ignore included links?
    60. 60. Can the developer add out-of-band links to her app?
    61. 61. What happens when an app relies on multiple APIs?Where is the state machine?
    62. 62. If the Twitter API had complied with HATEOAS
    63. 63. When Loren Brichter
    64. 64. Created Tweetie
    65. 65. Would he have been able to decide which user actions toinclude in his design?
    66. 66. Or would those decisions have been driven by the links inthe response from the Twitter API?
    67. 67. Nearly all popular web UIs adhere to HATEOAS.
    68. 68. Nearly all popular web APIs violate HATEOAS.
    69. 69. Why?
    70. 70. Let’s examine the two worlds.
    71. 71. I guarantee hypermedia is engine of appI decide where state I craft the user to click, aka experience, aka change state. state diagram. REST Interface App Browser App UI Server User App Developer
    72. 72. The person who crafts the experience (state diagram)and the app user have the REST interface between them.
    73. 73. And the hypermedia links are given directly to the appuser at runtime.
    74. 74. So the hypermedia in each response message isgenuinely the engine of application state.
    75. 75. This pattern is not limited to user interfaces.
    76. 76. We see the same pattern for syndication feeds.
    77. 77. I guarantee hypermedia is engine of app state I craft stories,I decide where categories & related to click, aka media, aka state change state. diagram. REST Interface App Feed Reader Feed Content User App Server Publisher
    78. 78. But the world of apps and web APIs seems different.
    79. 79. Interface App App 1 Developer 1App API Server AppUser App 2 Developer 2 App App 3 Developer 3
    80. 80. Interface I craft the user experience, I get no aka state diagram. App HATEOAS App 1I decide where Developer 1 respect. to click, aka change state. App API Server App User App 2 Developer 2 App App 3 Developer 3
    81. 81. The person who crafts the experience (state machine)and the app user do not have the REST interfacebetween them.
    82. 82. And the hypermedia links are not given directly to theapp user at runtime.
    83. 83. Instead, the hypermedia are given to the developer atdesign time.
    84. 84. And the developer decides which states are possible forthe app user at runtime.
    85. 85. We need a Yoda moment.
    86. 86. “ You must unlearn what you have learned. -Yoda
    87. 87. I used to call the world of popular, non-HATEOAS, non-SOAP web APIs, Pragmatic REST.
    88. 88. Oops.
    89. 89. How do we answer the questions many API teams areasking
    90. 90. 1. Should we go down the HATEOAS path?
    91. 91. As a practical matter, for many teams that previousquestion is the same as the next question.
    92. 92. 2. Should we include links in our responses?
    93. 93. But they have different answers.
    94. 94. 1. For an API to be HATEOAS-compliant it requires aclient app that is also HATEOAS-compliant.
    95. 95. A user-interface app driven by web APIs would be akin toa feed reader for syndicated content.
    96. 96. But designed to handle generic web APIs.
    97. 97. I guarantee hypermedia is engine of appI decide where state I craft a system of to click, aka interrelated resources, change state. aka state diagram. REST Interface App RESTful API API API Server User Client App Developer ?
    98. 98. Special thanks to @elasticpath for this metaphor.
    99. 99. There are interesting non-UI applications as well.
    100. 100. “ However, the style does not assume that all applications are browsers. In fact, the application details are hidden from the server by the generic connector interface, and thus a user agent could equally be an automated robot performing information retrieval for an indexing service, a personal agent looking for data that matches certain criteria, or a maintenance spider busy patrolling the information for broken references or modified content [39]. -Roy Fielding Architectural Styles and the Design of Network-based Software Architectures Chapter 5
    101. 101. If you’re not going down the HATEOAS client path, shouldyou include links anyway?
    102. 102. 2. If you think including links in the API response will behelpful for developers at design time, then go for it.
    103. 103. But I wouldn’t call it HATEOAS because those links areprobably not the engine of application state for the appuser at run time.
    104. 104. “ 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? -Roy Fielding “REST APIs must be hypertext-driven” Untangled: Musings of Roy T. Fielding
    105. 105. Here’s a call to action
    106. 106. We know what REST with the HATEOAS constraintis and isn’t.
    107. 107. We know what SOAP is and isn’t.
    108. 108. But we don’t have an intellectual framework forthe way so many popular apps and web APIs worktoday.
    109. 109. We need a really smart person
    110. 110. Who cares about web APIs
    111. 111. To examine the constraints of REST
    112. 112. The Constraints of REST1. Client-server2. Stateless server3. Cache4. Uniform interface a. Identification of resources b. Manipulation of resources through representations c. Self-descriptive messages d. Hypermedia as the engine of application state5. Layered System6. Code-On-Demand (optional)
    113. 113. While keeping in mind how custom apps are builtby people using web APIs
    114. 114. Interface App App 1 Developer 1App API Server AppUser App 2 Developer 2 App App 3 Developer 3
    115. 115. To give us a new foundation
    116. 116. The Constraints of ____1. ???2. ???3. ???4. ???5. ???6. ???
    117. 117. So that we will have a better shared idea of whatwe’re really doing
    118. 118. We will be able to communicate more effectively
    119. 119. And we will be able to create more value for theplanet and the people on it.
    120. 120. But please choose a nice, pronounceable acronym.
    121. 121. Further Exploring• http://steveklabnik.com/• http://pinboard.in/u:earth2marsh/t:hateoas/• http://www.ics.uci.edu/~fielding/pubs/dissert ation/top.htm• http://martinfowler.com/articles/richardsonM aturityModel.html• http://timelessrepo.com/haters-gonna- hateoas
    122. 122. Questions?
    123. 123. THANK YOUSubscribe to API webinars at:youtube.com/apigee
    124. 124. THANK YOUIRC#api-crafton freenode
    125. 125. THANK YOUQuestions and ideas to:groups.google.com/group/api-craft
    126. 126. THANK YOUContact me at:@landlessnessbrian@apigee.com

    ×