Pro Yearly is on sale from $80 to $50! »

Hypermedia: APIs of the Web

Hypermedia: APIs of the Web


  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

  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=""

    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": "", "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(''); (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":""}, ... ] } /
  13. /images/123 /images/123 { "data": { "src": "", "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 Edge cache JSON Control

    TTL with headers 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 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