Design Hypermedia APIs

5,738 views
5,628 views

Published on

0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
5,738
On SlideShare
0
From Embeds
0
Number of Embeds
65
Actions
Shares
0
Downloads
9
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

Design Hypermedia APIs

  1. 1. DESIGN HYPERMEDIA APIS Gustaf Nilsson Kotte / @gustaf_nk
  2. 2. OUR TASK Design an API for a kanban board. The API will have multiple clients.
  3. 3. KANBAN BOARD
  4. 4. API GTPS ies E/OT tm/ { } i:13 d 2, nm:"." ae .., dsrpin "." ecito: .., sau:"ako|okn|eiydn" tts bclgwrigvrf|oe
  5. 5. SERVER SIDE: ENFORCE RULES Don't trust clients
  6. 6. CLIENT SIDE: USER FRIENDLY Hide non-valid transitions Show primary transitions "Read the specification"
  7. 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. 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. 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. 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. 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. 12. WITHOUT HYPERMEDIA
  13. 13. PREFER FAT APIS OVER FAT CLIENTS
  14. 14. http://martinfowler.com/articles/richardsonMaturityModel.html
  15. 15. HYPERMEDIA APIS
  16. 16. WHAT IS THE HYPERMEDIA CONSTRAINT? You do stuff by reading pages and then either follow links or submit forms. — Jon Moore
  17. 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. 18. 1. EVALUATE PROCESSES
  19. 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. 20. 2. CREATE STATE MACHINE
  21. 21. FIRST ATTEMPT...
  22. 22. Simplified view
  23. 23. Inline actions
  24. 24. Better root node
  25. 25. 3. EVALUATE MEDIA TYPES
  26. 26. H-FACTORS http://amundsen.com/hypermedia/hfactor/
  27. 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. 28. 4. CREATE OR CHOOSE MEDIA TYPES
  29. 29. HTML HAL Collection+JSON Siren JSON-LD Atom SVG OData
  30. 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. 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. 32. MORE... Great for learning about hypermedia!
  33. 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. 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. 35. 5. IMPLEMENTATION
  36. 36. 6. REFINEMENTS
  37. 37. (Better root node)
  38. 38. Cache profiles analysis: Separate Board and Navigation
  39. 39. DONE! JUST ONE MORE THING... :)
  40. 40. WRITING A HYPERMEDIA AWARE CLIENT
  41. 41. Not harder than writing a "regular" client, just different...
  42. 42. ...which means it's harder, since new to many developers :(
  43. 43. GENERIC VS SPECIFIC CLIENT?
  44. 44. STANDARDIZED DOMAIN VS WALLED GARDEN "Atom client" vs "Twitter client" However, standard media types still have value!
  45. 45. USE THE AFFORDANCES Link relations (navigational state) Form relations (server state)
  46. 46. DEMO: CHANGING THE APPLICATION
  47. 47. DEMO: RUBY CONSOLE CLIENT
  48. 48. WHERE'S THE APPLICATION?
  49. 49. SUMMARY
  50. 50. BOOKS Steve Klabnik , Designing Hypermedia APIs Mike Amundsen , Building Hypermedia APIs with HTML5 and Node
  51. 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

×