Hypermedia: APIs of the Web

Transcript

1. Hypermedia Hypermedia APIs of the Web APIs of the Web Sébastien Cevey @theefer APIDays / APIStrat Berlin, 24th April 2015
2. About me About me Sébastien Cevey @theefer Hypermedia Hypermedia APIs APIs
3. REST REST “REpresentational State Transfer” Architectural style inspired by the design of the Web (Roy Fielding's dissertation, 2000) RESTful API RESTful API REST applied to design scalable APIs
4. Pick a baseline network protocol 0. HTTP protocol* 0. HTTP protocol* POST /getImage imageId = 123 client server { ... } * not necessarily HTTP, but usually is
5. Model “things” as Resources Give Resources a Uniform Resource Identifier 1. URIs 1. URIs GET client server { ... } /images/123
6. Map actions to HTTP methods 2. Verbs 2. Verbs GET POST PUT PATCH DELETE retrieve create/update replace partial update delete PUT { ... } client server { ... } /images/123
7. No, we’re not done yet.
8. Hypermedia Hypermedia Key constraint of REST and the Web “the simultaneous presentation of information and controls such that the information becomes the affordance through which the user obtains choices and selects actions” (Fielding, 2008) Hypermedia API ≈ strict REST API
9. 3. Hypermedia Controls 3. Hypermedia Controls <article class="image"> <img src="http://example.io/cat.jpg" width="800" height="600"> <a href="/images/123/crops">crops</a> <form action="/images/123" method="POST"> <div>Resize dimensions</div> <label><input name="width" type="number"> width</label> <label><input name="height" type="number"> height</label> <input type="submit" value="Update"> </form> </article> Embed controls in API response: Links to related resources Forms to describe actions
10. API optimised API optimised XML or JSON + Hypermedia semantics Media-Types Media-Types { "properties": { "type": "image", "url": "http://example.io/cat.jpg", "width": 800, "height": 600, }, "links": [ { "rel": ["crops"], "href": "/images/123/crops" } ], "actions": [{ "name": "resize", "title": "Resize dimensions", "href": "/images/123", "method": "POST", "fields": [ { "name": "width", "type": "number" }, { "name": "height", "type": "number" } ] }] } Content-Type: application/vnd.siren+json Formats Formats , , , , … HAL Siren JSON-LD Uber Argo
11. “HATEOAS” “HATEOAS” Hypermedia As The Engine Of Application State GET client server / / / client.resource('https://api.media.gu.com'); (JavaScript library for argo APIs) theseus
12. /images/123 Follow link Follow link GET client server /images/123 /images/123 / resource.follow('image', {id: '123'}); { "data": { "description": "This is the Media API" }, "links": [ {"rel":"image", "href": "/images/{id}"}, {"rel":"cropper","href":"https://cropper.media.gu.com"}, ... ] } /
13. /images/123 /images/123 { "data": { "src": "http://example.io/cat.jpg", "width": 600, "height": 800, "credit": "Graham" }, "actions": [{ "name": "resize", "title": "Resize dimensions", "method": "PATCH", "href": "/images/123", "fields": [ { "name": "width", "type": "number" }, { "name": "height", "type": "number" } ] }] } resource.perform('resize', { width: 300, height: 400 }); {width: 300, height: 400} client server /images/123 PATCH Update state Update state /images/123 /images/123 /images/123
14. State transfer State transfer Resources as state Resources as state Model state on client and server Hypermedia as affordances Hypermedia as affordances Links to other resources Forms to describe available actions on resources Verbs to transfer Verbs to transfer Synchronise state between client and server Apply changes to both
15. Benefits of Benefits of Hypermedia APIs Hypermedia APIs
16. “The best network-based application performance is obtained by not using the network”
17. HTTP POST, TCP Cacheable Cacheable client server /images/123 browser cache CDN edge cache caching proxy client server app cache server cache Hypermedia RPC
18. Cacheable Cacheable 0 1 Uniform HTTP interface, standard semantics Resource URI as cache key Verb semantics: GET is safe & idempotent 2 Layer standard HTTP components Layer standard HTTP components CDN, proxy, server, etc. Control caching from the server Control caching from the server Headers: Cache-Control, Vary, E-Tag, etc. Transparently respected downstream
19. Cache stories Cache stories theguardian.com theguardian.com Edge cache JSON Control TTL with headers zik.ca zik.ca Serve expensive responses from file on disk Split out and link to dynamic part of response
20. Discoverable Discoverable URI as explicit reference (unlike IDs) Links and forms self-documenting (in-band) 1 3 Web-like Web-like Browse API from the root or any resource Submit forms while exploring in browser Resource address returns its data
21. Discoverable Discoverable API federation API federation Links to Media API from our Content API Self-service Self-service Give root of the Media API to other teams Service index in Media API
22. Discoverable Discoverable API as UI API as UI Use content negociation JSON 㱺 HTML URI templates 㱺 forms http://zik.ca/.html API as REPL API as REPL client Works with any APIs Dove Argo
23. Evolveable Evolveable Persistent URIs Clients rely on links, not out-of-band config Extensible Extensible Add data properties Add links & form fields Ignored if unsupported Server configures clients Server configures clients Only config is API root No URL construction Change link targets transparently 1 3 Composeable Composeable Add new services via links and forms Shared media-type helps Avoids monolithic library
24. Simple Simple Plain HTTP JSON or XML + Hypermedia layer Visibility Visibility Send URL around Server request logs Browser network panel Wireshark Scalable Scalable cURL Bookmarklets Apple Scripts Small web clients Mobile apps Large single-page apps 0 3 1 2
25. Authoritative Authoritative Conditional links/forms drive the UI Conditional links/forms drive the UI Based on permissions, business logic Avoids hardcoding rules in both server & client Server rules can change, apply to all clients if valid, expose link if invalid, omit link Requirement: can only crop valid images Links & forms as affordances 3
26. Forms drive client-side validation Forms drive client-side validation Expose constraints in form fields Apply to HTML UI form Avoids hardcoding rules in both server & client R&D e.g. required, min/max length, “email”, etc Authoritative Authoritative
27. Limitations Limitations Performance Performance Serialisation/Deserialisation Payload size Plain JSON: 23.0KB Argo+JSON: 37.4KB +40% gzipped 4.4KB 5.1KB +15% No data schema No data schema Versioning Versioning State transfer model State transfer model Avoid side-effects Poll, no PUSH Weak tooling Weak tooling
28. References References Leonard Richardson, Mike Amundsen RESTful Web APIs Roy Fielding Architectural Styles and the Design of Network-based Software Architectures Martin Fowler Richardson Maturity Model
29. Hypermedia Hypermedia Uniform HTTP interface Uniform HTTP interface Cacheable for performance Simple to integrate and debug Resources model state Resources model state Verbs transfer state Verbs transfer state Hypermedia controls as affordances Hypermedia controls as affordances Discoverable for developers Dynamic link structure allows evolveability Authoritative source of client actions through forms
30. Thank you! Thank you! Sébastien Cevey @theefer https://slides.com/theefer/hypermedia-apidays