1. DESIGN HYPERMEDIA APIS
Gustaf Nilsson Kotte / @gustaf_nk

2. OUR TASK
Design an API for a kanban board.
The API will have multiple clients.

3. KANBAN BOARD

4. API
GTPS ies
E/OT tm/
{
}
i:13
d 2,
nm:"."
ae ..,
dsrpin "."
ecito: ..,
sau:"ako|okn|eiydn"
tts bclgwrigvrf|oe

5. SERVER SIDE: ENFORCE RULES
Don't trust clients

6. CLIENT SIDE: USER FRIENDLY
Hide non-valid transitions
Show primary transitions
"Read the specification"

7. SPECIFICATION
Ipeettesaemcieo tergt
mlmn h tt ahn n h ih.
Tepiayato frec saei te
h rmr cin o ah tt s h
"onad arw ecp frtesae
dwwr" ro, xet o h tt
"oe weetepiayato i
dn" hr h rmr cin s
t mv teie bc t te"okn"sae
o oe h tm ak o h wrig tt.

8. CLIENT SIDE VARIATIONS
fnto nxSae(tm {
ucin etttsie)
i (tmsae= 'ako'
f ie.tt = bclg)
rtr [wrig]
eun 'okn';
es i (tmsae= 'okn'
le f ie.tt = wrig)
rtr [bclg,'eiy]
eun 'ako' vrf';
..
.
}
fnto gtrmr(tt){
ucin ePiaysae
i (tmsae= 'ako'
f ie.tt = bclg)
rtr 'okn'
eun wrig;
..
.
}

9. CLIENT SIDE VARIATIONS
fnto nxSae(tm {
ucin etttsie)
dc ={
it
'ako'= [wrig]
bclg > 'okn',
'okn'= [bclg vrf',
wrig > 'ako, eiy]
..
.
}
rtr dc[tmsae;
eun itie.tt]
fnto gtrmr(tt){
ucin ePiaysae
i (tmsae= 'ako'
f ie.tt = bclg)
rtr 'okn'
eun wrig;
..
.
}

10. CLIENT SIDE VARIATIONS
fnto nxSae(tm {
ucin etttsie)
dc ={
it
'ako'= [wrig]
bclg > 'okn',
'okn'= [bclg vrf',
wrig > 'ako, eiy]
..
.
}
rtr dc[tmsae;
eun itie.tt]
fnto iPiaysae nxSae {
ucin srmr(tt, ettt)
rtr nxSae= nxSae(tt)ls(;
eun ettt = etttssae.at)
}

11. CLIENT SIDE VARIATIONS
fnto nxSae(tm {
ucin etttsie)
vrsaeahn =nwSaeahn(ofjo)
a ttMcie
e ttMciecn.sn;
}
rtr saeahn.eTastosie.tt)
eun ttMciegtrniin(tmsae;
fnto iPiaysae nxSae {
ucin srmr(tt, ettt)
rtr nxSae= nxSae(tt)ls(;
eun ettt = etttssae.at)
}
Many possibilities!

12. WITHOUT HYPERMEDIA

13. PREFER FAT APIS OVER FAT CLIENTS

14. http://martinfowler.com/articles/richardsonMaturityModel.html

15. HYPERMEDIA APIS

16. WHAT IS THE HYPERMEDIA CONSTRAINT?
You do stuff by reading pages
and then either
follow links or submit forms.
— Jon Moore

17. DESIGN PROCESS
1.
2.
3.
4.
5.
6.
Evaluate processes
Create state machine
Evaluate media types
Create or choose media types
Implementation
Refinements
http://www.designinghypermediaapis.com

18. 1. EVALUATE PROCESSES

19. 1. EVALUATE PROCESSES
Cletos "or" bclg wrig vrf,dn
olcin: bad, ako, okn, eiy oe
Snl:dtis ei
ige eal, dt
Wie bigal t cag tesaeo a ie
rt: en be o hne h tt f n tm
acrigt terls
codn o h ue

20. 2. CREATE STATE MACHINE

21. FIRST ATTEMPT...

22. Simplified view

23. Inline actions

24. Better root node

25. 3. EVALUATE MEDIA TYPES

26. H-FACTORS
http://amundsen.com/hypermedia/hfactor/

27. H-FACTORS FOR OUR API
LO: Support for out-bound navigational links (HTTP GET)
LN: Support for non-idempotent updates (HTTP POST)
CL: Support for adding semantic meaning to link elements
using link relations

28. 4. CREATE OR CHOOSE MEDIA TYPES

29. HTML
HAL
Collection+JSON
Siren
JSON-LD
Atom
SVG
OData

30. Name
Summary
Read/write
Comment
HAL
Resources and relations
R
Write support with addon
Collection+JSON
Collections over JSON
RW
Siren
~ JSON port of HTML
RW
JSON-LD
~ RDF over JSON
R

31. USE HTML FOR HYPERMEDIA APIS
Lots of hypermedia controls
Old, standardized, everybody knows HTML
Good tooling support
https://vimeo.com/20781278
http://codeartisan.blogspot.se/2012/07/using-html-as-media-type-for-your-api.html
http://amundsen.com/hypermedia/html/

32. MORE...
Great for learning about hypermedia!

33. EXAMPLE: MICROFORMATS2, ENTITIES
<icas"-tm>
l ls=hie"
<i cas"-ae>% ie.ae%<dv
dv ls=pnm"<= tmnm >/i>
<i cas"-tts>% ie.tts%<dv
dv ls=psau"<= tmsau >/i>
<i cas"-ecito"<=ie.ecito %<dv
dv ls=pdsrpin>% tmdsrpin >/i>
<i cas"-om"
dv ls=pfrs>
..
.
<dv
/i>
<i cas"-ik"
dv ls=plns>
..
.
<dv
/i>
<l>
/i

34. EXAMPLE: MICROFORMATS2, FORMS
<i cas"-om"
dv ls=pfrs>
<omdt-e=mv bclg ato=/tm/ako"mto=PS"
fr aarl"oe ako" cin"iesbclg ehd"OT>
<nu nm=i"tp=hde"vle""
ipt ae"d ye"idn au=4>
<nu tte"umt tp=sbi"vle"oet bclg>
ipt il=sbi" ye"umt au=Mv o ako"
<fr>
/om
<omdt-e=mv vrf nx"ato=/tm/eiy mto=PS"
fr aarl"oe eiy et cin"iesvrf" ehd"OT>
<nu nm=i"tp=hde"vle""
ipt ae"d ye"idn au=4>
<nu tte"umt tp=sbi"vle"oet vrf"
ipt il=sbi" ye"umt au=Mv o eiy>
<fr>
/om
<dv
/i>

35. 5. IMPLEMENTATION

36. 6. REFINEMENTS

37. (Better root node)

38. Cache profiles analysis: Separate Board and Navigation

39. DONE! JUST ONE MORE THING... :)

40. WRITING A HYPERMEDIA AWARE CLIENT

41. Not harder than writing a "regular" client, just different...

42. ...which means it's harder, since new to many developers :(

43. GENERIC VS SPECIFIC CLIENT?

44. STANDARDIZED DOMAIN
VS
WALLED GARDEN
"Atom client" vs "Twitter client"
However, standard media types still have value!

45. USE THE AFFORDANCES
Link relations (navigational state)
Form relations (server state)

46. DEMO: CHANGING THE APPLICATION

47. DEMO: RUBY CONSOLE CLIENT

48. WHERE'S THE APPLICATION?

49. SUMMARY

50. BOOKS
Steve Klabnik , Designing Hypermedia APIs
Mike Amundsen , Building Hypermedia APIs
with HTML5 and Node

51. THANK YOU!
Gustaf Nilsson Kotte / @gustaf_nk
Code: https://github.com/gustafnk/kanban-awd-api
Demo: http://kanban-awd.herokuapp.com/ and http://kanban-api.herokuapp.com
Slides: http://www.slideshare.net/GustafKotte/design-hypermedia-apis