!Irakli!Nadareishvili!

Director!of!API!Strategy,!CA!Technologies!!

@inadarei!

!?! BUT WHY?

2013:

80 devices /sec

Source:!Cisco!

2014:

100 devices /sec

Source:!Cisco!

2020:

250 devices /sec

Source:!Cisco!

2020:

50bn conn. devices

Source:!Cisco!

You Assume Control?

!

Hypermedia-Oriented Style

@inadarei

What!if!the!server!could!dynamically!tell!the!client!what!the!client!can!do!and!how,!guiding!the!client!from!one!desired!state!to!another?!

Avoid&'ght&coupling&and&hardcoding!&

Response = Data + Controls

@inadarei

API!server!would!have!to!send!client!not!just!sta$c!data,!but!also!controls!describing!API!affordances.!

Hypermedia per Fielding

Architectural!Styles!and!the!Design!of!NetworkFbased!SoGware,!2001!F!Roy!T.!Fielding!

"Hypermedia!is!defined!by!the!presence!of!applicaQon!control!informaQon!embedded!within,!or!as!a!layer!above,!the!presentaQon!of!informaQon�!(2001)!

Affordances

@inadarei

Theory!of!Affordances,!1979!F!James!J.!Gibson!!

Affordances!are!all!"acQon!possibiliQes"!latent!in!the!environment.!!

Affordances

@inadarei

Affordances

@inadarei

Affordances’re key to a good design Imagine!a!car!or!a!building!that!you!couldn't!possibly!use,!unless!you!had!a!manual.!That!sounds!silly,!we!don't!build!cars!or!buildings!like!that.!Yet,!that!is!exactly!how!we!build!APIs!today.!

Familiarity Creates Usability Are!all!cars!exactly!the!same?!No.!Can!we!do!basic!things!with!any!car,!once!we!understand!how!cars!in!general!work?!Yes!!Do!we!need!to!read!a!manual!for!that?!No!!

Common vocabulary:

in Media Types paginaQon,!internaQonalizaQon,!templated!querying,!data!updates…!

Semantic GAP

Profiles

[Profile!link!relaQon!defines]!addiQonal!semanQcs!that!can!be!used!to!process!a!resource!representaQon,!such!as!constraints,!convenQons,!extensions,!or!any!other!aspects!that!do!not!alter!the!basic!media!type!semanQcs!

RFC6906:!!

Profiles!can!be!combined,!meaning!that!a!single!resource!representaQon!can!conform!to!zero!or!any!number!of!profiles.!

Profile Examples:

1.  XMDP (HTML-only)http://gmpg.org/xmdp/

2.  PMP (CDoc-only)https://github.com/publicmediaplatform/pmpdocs/wiki/Profile-profile

3.  ALPShttp://www.ietf.org/id/draft-amundsen-richardson-foster-alps-00.txt

And!many!others…!

OMG! This Feels So Complicated!

@inadarei

No, It Is Not Complicated!

@inadarei

You!are!already!very!familiar!with!all!of!it:!World!Wide!Web!is!a!perfect!Hypermedia!system!and!HTML!is!one!of!the!most!successful!hypermedia!types.!

When in doubt:

@inadarei

Always!draw!parallels!with!web!and!think!about:!“—&Ok,&so&how&would&I&do&this&if&I&was&&just&building&a&website&and&this&was&just&HTML?”&

Bingo! Except!HTML![usually]!deals!with!unstructured!content!and!is!not!always!appropriate!for!APIs!that!marshal!structured!data.!Let’s!do!a!ligle!more!of!the!learning!thing.!

7-Step Design Process

1.  List Semantic Descriptors2.  Draw a State Diagram3.  Reconcile Names4.  Choose a Media Type5.  Write a Profile6.  Implementation7.  Publication

Source:!Richardson!&!Amundsen,!Resiul!Web!APIs!

#2 State Diagram Example: Blog

List of blog posts Create blog post

Save post

#3 Reconcile Names 1.  IANA Link Relations

http://www.iana.org/assignments/link-relations/link-relations.xhtml

2.  Microformats Link Relations http://microformats.org/wiki/existing-rel-values

3.  Dublin Core Metadata Element Set, Version 1 http://dublincore.org/documents/dces/

Source:!M.!Amundsen,!UBER!Hypermedia!Format!

#4 Choose a Hypermedia Type

1.  UBER (http://uberhypermedia.org)2.  Collection+JSON (Col.Doc)3.  HAL4.  Siren5.  JSON:API6.  HTML (yeap! Just ask Jon Moore)

7-Step Design Process

1.  List Semantic Descriptors2.  Draw a State Diagram3.  Reconcile Names4.  Choose a Media Type5.  Write a Profile6.  Implementation7.  Publication

Source:!Richardson!&!Amundsen,!Resiul!Web!APIs!

Who Uses Hypermedia APIs? 1.  AWS Streaming API2.  ElasticPath Cortex3.  Comcast4.  Microsoft Lync5.  Paypal6.  Github7.  FoxyCart8.  Huddle9.  Public Media Platform10.  …

You?

What now? 1.  Follow @mamund2.  Follow @apiacademy3.  Follow @darrel_miller4.  Follow @jharmn5.  Follow @kinlane (always)6.  Follow @inadarei (if you want)7.  Dave Goldberg’s Hypermedia Resources:

http://davejonathangoldberg.github.io/apis/hypermedia/2014/08/08/hypermedia-resources/

8.  Hypermedia Google Group https://groups.google.com/forum/#!forum/hypermedia-web

9.  UBER Google Group https://groups.google.com/forum/#!forum/uber-hypermedia

Be involved. This is a super-active and exciting space!