Your SlideShare is downloading. ×
  • Like
Design Hypermedia APIs
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Now you can save presentations on your phone or tablet

Available for both IPhone and Android

Text the download link to your phone

Standard text messaging rates apply

Design Hypermedia APIs

  • 5,394 views
Published

 

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
5,394
On SlideShare
0
From Embeds
0
Number of Embeds
3

Actions

Shares
Downloads
6
Comments
0
Likes
2

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 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