Benefits of Hypermedia API
Download as PPTX, PDF5 likes3,889 views
This document discusses the benefits of hypermedia APIs, which embed application control information within or above the presentation layer. Key benefits include explorable APIs with inline documentation, simplified client logic since the server handles business logic and URL structure, and increased flexibility/evolvability as the server can modify URLs, offload content, and upgrade without breaking clients. Examples show how a bank account balance API provides semantic links that a client follows to perform actions like withdrawals, and how the server can change URLs, offload content, and upgrade without breaking hypermedia-driven clients. In closing, the document advocates adhering to the hypermedia constraint, aiming for a "billboard" API, and decoupling clients from servers.
Benefits of Hypermedia API
- 1. BENEFITS OF HYPERMEDIA APIS Paulo Gandra de Sousa pagsousa@gmail.co m
- 2. Hypermedia is defined by the presence of application control information embedded within, or as a layer above, the presentation of information. Mike Amudsen 3 “
- 3. THE HYPERMEDIA CONSTRAINT Hipermedia as the engine of application state * * HATEOAS
- 4. “ HYPERMEDIA IS THE ENGINE Hypermedia payloads carry more information than just the data stored on the server. Hypermedia payloads carry two types of vital metadata: metadata about the data itself and metadata about the possible options for modifying the state of the application at that moment. Mike Amudsen 5
- 5. THE HYPERMEDIA CONSTRAINT The application is therefore an engine that moves from one state to the next by examining and choosing from among the alternative state transitions in the current set of representations. Roy Fielding 6 “
- 6. IMMEDIATE BENEFITS Explorable API Inline documentation Simple client logic 7
- 7. “BILLBOARD” ENDPOINT GET /api 8 200 Ok <links> <link rel=“…” href=“…”/> <link rel=“…” href=“…”/> ... </links>
- 8. LINKED DATA PRINCIPLES 1.Use URIs as names for things 2.Use HTTP URIs so that people can look up those names. 3.When someone looks up a URI, provide useful information, using the standards 4.Include links to other URIs so that they can discover more things. Tim Berners-Lee (2006) http://www.w3.org/DesignIssues/LinkedData.html 9
- 9. EXAMPLE: CHECK BANK ACCOUNT BALANCE EXPLORABLE API + INLINE DOCUMENTATION GET /account/12345 200 OK <?xml version="1.0"?> <account> <account_number>12345</account_number> <link rel=“self” href=“/account/12345” /> <balance currency="usd">100.00</balance> <link rel=“http://bank.org/rel/first-subscriber" href="/customer/123" /> <link rel=“http://bank.org/rel/subscribers" href="/account/12345/subscriber" /> <link rel="http://bank.org/rel/deposit" href="/account/12345/deposit" /> <link rel="http://bank.org/rel/withdraw" href="/account/12345/withdraw" /> <link rel="http://bank.org/rel/transfer" href="/account/12345/transfer" /> <link rel="http://bank.org/rel/close" href="/account/12345/close" /> </account> 10 Semantic and documentati on Use URI as names Explorable
- 10. CLIENT SIMPLICITY Coupled to implementation res = GET /account/123 If enough-funds() then msg = build-withdraw- message() url = build-url-from- template() POST msg @ url Endif Hypermedia-driven res = GET /account/123 If res.hasLink(“withdraw”) then msg = build-withdraw- message() POST msg @ res.link(“withdraw”) Endif 11 Needs to know URL template Business logic spills out to client Server handles Business logic Server manages URL structure VS
- 11. FLEXIBILITY & EVOLUTION Server takes ownership of URL Offloading content Upgrading 12
- 12. EXAMPLE: CHECK BANK ACCOUNT BALANCE SERVER MODIFIES URL STRUCTURE GET /account/12345 200 OK <?xml version="1.0"?> <account> <account_number>12345</account_number> <link rel=“self” href=“/account/12345” /> <balance currency="usd">100.00</balance> <link rel=“http://bank.org/rel/first-subscriber" href=“/crm/123?role=customer" /> <link rel=“http://bank.org/rel/subscribers" href="/account/12345/subscriber" /> <link rel="http://bank.org/rel/deposit" href="/account/12345/deposit" /> <link rel="http://bank.org/rel/withdraw" href="/account/12345/withdraw" /> <link rel="http://bank.org/rel/transfer" href="/account/12345/transfer" /> <link rel="http://bank.org/rel/close" href="/account/12345/close" /> </account> 13 New URL; no problem client just follows it
- 13. EXAMPLE: CHECK BANK ACCOUNT BALANCE CONTENT OFFLOADING GET /account/12345 200 OK <?xml version="1.0"?> <account> <account_number>12345</account_number> <link rel=“self” href=“/account/12345” /> <balance currency="usd">100.00</balance> <link rel=“http://bank.org/rel/first-subscriber" href=“http://one-crm.com/api/tenant/bankABC/prospect/754" /> <link rel=“http://bank.org/rel/pricing" href=“http://bankABC.cdn.akamai.com/static/pricing" /> ... </account> 14 Content offloaded to 3rd party providers
- 14. EXAMPLE: CHECK BANK ACCOUNT BALANCE SERVER UPGRADE GET /account/12345 200 OK <?xml version="1.0"?> <account> <account_number>12345</account_number> <link rel=“self” href=“/account/12345” /> <balance currency="usd">100.00</balance> <link rel=“http://bank.org/rel/first-subscriber" href=“http://one-crm.com/api/tenant/bankABC/prospect/754" /> <link rel=“http://bank.org/rel/pricing" href=“http://bankABC.cdn.akamai.com/static/pricing" /> <link rel="http://bank.org/rel/deposit" href="/account/12345/deposit" type=“application/vnd.bankABC.deposit.v2+xml, application/vnd.bankABC.deposit+xml” /> ... </account> 15 New relationship; only V2 clients will know it New media type accepted; only V2 clients will know it
- 15. 16 CLOSINGS
- 16. 1. Adhere to the hypermedia constraint 2. Aim for a “billboard” API 3. Decouple client and server
- 17. REFERENCES
- 18. Jørn Wildt (2013) Selling the benefits of hypermedia APIs. http://soabits.blogspot.no/2013/12/selling-benefits- of-hypermedia.html David (2012) Getting hyper about hypermedia APIs. https://signalvnoise.com/posts/3373-getting-hyper- about-hypermedia-apis “Architectural Styles and the Design of Network-based Software Architectures”, PhD Thesis (2000), Roy Thomas Fielding. http://www.ics.uci.edu/~fielding/pubs/dissertation/top. htm Leonard Richardson, Mike Amundsen, RESTful web APIs. O’Reily Media. ISBN: 1449358063
Editor's Notes
- #2: http://www.v3.co.uk/IMG/063/257063/web-http-url-address-internet-online-www.jpg
- #5: From wikipedia: http://en.wikipedia.org/wiki/HATEOAS This principle is the key differentiator between a REST and most other forms of client server system. Rather than the actions and interfaces a client may use being defined elsewhere, such as in a WSDL file or predefined in the client code, the principle is that the hypermedia in eachserver response will contain links that correspond to all the actions that the client can currently perform. Therefore, dependent on the current application state, every server response describes the new actions that are available. The server can change the range of allowable responses in a dynamic way, and a client should adapt its behavior to these changes. A client of a RESTful application need only know a single fixed URL to access it. All future actions should be discoverable dynamically from hypermedia links included in the representations of the resources that are returned from that URL. Standardized media types are also expected to be understood by any client that might use a RESTful API. Application state transitions are driven by a combination of the known processing rules for each media type, client selection from the server-provided choices in representations received, and the user's manipulation of those representations. Thus interactions are driven by hypermedia, rather than by any out-of-band information.[1] If necessary, the client’s knowledge of media types, resource communication mechanisms, and user interaction, may be improved on-the-fly by the transmission of code-on-demand from the server to the client as defined elsewhere in the REST architecture.[2]
- #8: http://soabits.blogspot.no/2013/12/selling-benefits-of-hypermedia.html
- #9: Single entry point URI /api Everything else is discovered thru links
- #10: http://www.w3.org/DesignIssues/LinkedData.html
- #11: Based on http://restcookbook.com/Basics/hateoas/
- #13: http://soabits.blogspot.no/2013/12/selling-benefits-of-hypermedia.html
- #14: Based on http://restcookbook.com/Basics/hateoas/
- #15: Based on http://restcookbook.com/Basics/hateoas/
- #16: Old clients will ignore the relationships they don’t understand and will continue to send V1 representations while new clients will understand the new relationships and will take advantage of V2 representations
- #17: http://www.newswire.com/blog/wp-content/uploads/2015/02/Expert-Strategies-for-Writing-Your-Press-Release-Summary.jpg
- #19: http://www.pdgm.com/getmedia/49986e29-2fba-4629-8a09-591205b91ed4/Library_1400_800.jpg.aspx