Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Designing Hypermedia APIs

Nate Abele
August 28, 2014

Designing Hypermedia APIs

Nate Abele

August 28, 2014
Tweet

More Decks by Nate Abele

Other Decks in Technology

Transcript

  1. The Vanity Slide ❖ Former lead developer, CakePHP! ❖ Founder,

    Li3 (a.k.a. Lithium)! ❖ Member, AngularUI team! ❖ Lead Developer, AngularUI Router! ❖ Architect-in-Chief, Radify! ❖ Highly opinionated, sometimes right! ❖ @nateabele / [email protected]
  2. Foundation: REST Level 0 Level 1 Level 2 Level 3

    RPC HTTP /soap /service …/posts …/comments …/users POST /users GET /users/nate { name: nate } * See: Richardson Maturity Model GET /users/nate/posts GET /users/nate Accept: application/vnd.somethinguseful+json
  3. Hypermedia 101 GET http://my.app/tasks HTTP/1.1 Accept: application/hal+json ! [{ title:

    "Finish the demo", completed: false, _links: { self: { href: “http://my.app/tasks/1138” }, owner: { href: “http://my.app/users/nate” }, subtasks: { href: “http://my.app/tasks/1138/tasks” } } }]
  4. Problems ❖ …built an app with Facebook Connect?! ❖ …built

    an app with Facebook anything?! ❖ …published an API, then changed the database schema?! ❖ …read an API doc, just to see how resources are related? Ever…
  5. Versioning ❖ A way of managing change over time! ❖

    Different options, different tradeoffs! ❖ Considerations! ❖ Maintenance for you! ❖ Maintenance for consumers! ❖ Complexity over time! ❖ Operational overhead
  6. Versioning: Version Numbers ❖ Explicit communication, manual intervention! ❖ Blocking;

    waterfall release cycle! ❖ Good for “local” dependencies
  7. Versioning: Content Negotiation GET http://my.app/users/nate HTTP/1.1 Accept: application/vnd.radify.user+json ! {

    name: “Nate Abele", title: “Architect”, address: “1 Rad Way, Philadelphia, PA” }
  8. Versioning: Content Negotiation GET http://my.app/users/nate HTTP/1.1 Accept: application/vnd.radify.user-addr+json ! {

    name: “Nate Abele", title: “Architect”, address: { street: “1 Rad Way”, city: “Philadelphia”, state: { name: “Pennsylvania”, abbr: “PA” }, country: { name: “United States”, abbr: “US” } } }
  9. Versioning: New Resources GET http://my.app/users/nate HTTP/1.1 Accept: application/vnd.radify.user+json ! {

    name: “Nate Abele", title: “Architect”, address: “1 Rad Way, Philadelphia, PA”, _links: { address: { href: “http://my.app/users/nate/address” } } }
  10. Versioning: Feature Flags GET http://my.app/users/nate?better_addresses=1 GET http://my.app/users/nate Go-Faster: 1 PATCH

    http://my.app/users/nate { new_email_templates: true } POST http://my.app/transaction-involving-mail $_SERVER[“EXPERIMENTAL”] = ALL_THE_THINGS GET http://beta.my.app/users/nate See also: chrome://flags
  11. Versioning: Feature Flags ❖ Implicit: never breaks clients! ❖ Clean

    boundary between server and clients! ❖ Agile: incremental evolution, no ‘all-or-nothing’ decisions! ❖ Good for network dependencies! ❖ Granular; cascading
  12. Versioning: Feature Flags ❖ Server-side! ❖ Per environment (local, remote)!

    ❖ Per deploy (beta/release, staging/production)! ❖ Per instance (for internal testing, segmenting etc.)! ❖ Client-side! ❖ Per account (preferences)! ❖ Per session (if using tokens/cookies)! ❖ Per request (headers, query params, etc.)
  13. Design Considerations ❖ Provide links to related resources! ❖ The

    network is slow: collate relevant data to send over the wire! ❖ Give the people what they want! ❖ Also: no database IDs!
  14. class Projects extends li3_resources\action\Resource { ! protected function _mappers() {

    return [ 'Fields' => [ 'name', 'slug', 'created' => function($project) { return $project->_id->getTimestamp(); } ], 'Links', 'Schema', 'FlagAsNew' => ['+1 weeks’], 'Embed' => [ 'Permissions' => [ 'conditions' => ['approved' => true] 'fields' => [. . .] ]] ] } }
  15. class Links { ! public function types() { return ['json',

    'xml']; } ! public function methods() { return ['GET']; } ! public function apply($request, $object, array $results) { // ... } }
  16. People to follow ❖ Mike Amundsen @mamund! ❖ Steve Klabnik

    @steveklabnik! ❖ Luke Stokes @lukestokes! ❖ Kevin Swiber @kevinswiber