Successfully reported this slideshow.

More Related Content

API Design choices

  1. 1. API Designchoices<br />@drabinovich<br />
  2. 2. REST on top of HTTP Organizeeverythingaround“Resources”https://api.mercadolibre.com/sites/MLA https://api.mercadolibre.com/users/4605484<br />
  3. 3. Use standard HTTP Verbs<br />PUT /users/4605484 {last_name: “Fagúndez” }<br />
  4. 4. Makeyour API usable<br />APIs exist *not only* for machines<br />Conventions are key to a great usability. <br /><ul><li> “AR” vs “0001” (ISO codes over proprietary codes)
  5. 5. “seller_id” vs “customer_id” (avoid the DOCS check)
  6. 6. “condition: used” over “used:true” (scalable!)
  7. 7. Design for canonical cases (de-normalize wisely)
  8. 8. Perform API Usability testing (subjects are developers)</li></li></ul><li>ProvideIntrospection<br />Getmetadatausing STD HTTP “Options” Verb<br /> OPTIONS /sites/MLA<br />https://api.mercadolibre.com/sites/MLA<br />
  9. 9. AutomaticPretty-Print<br />PerformingGETsfrom a Browser<br />
  10. 10. ProvideSelection<br />Choosethefieldsto be returned<br />/items/MLA121484389?attributes=title<br />{<br />title: "Boomerang Artesanales De Alta Calidad - Exclusivos -"<br />}<br />
  11. 11. Multiget<br />Get N resources at once<br />/items?ids=MLA121484389,MLA125002468&attributes=title<br />[<br /> -{<br />title: "Boomerang De Diseño Australiano Con Retorno Garantizado"<br /> }<br /> -{<br />title: "Boomerang Artesanales De Alta Calidad – Exclusivos"<br /> }<br />]<br />
  12. 12. Searchonresources<br />Complexquerieson a resource<br />/users/search?nickname=LEWIS_CARROLL<br />
  13. 13. Pagination<br />Managelargeresultsets<br />/sites/MLA/search?q=boomerang&limit=2&offset=10<br />
  14. 14. Thereis no free lunch<br />Selection, Multiget, Search<br />are REST violationswithhiddencosts<br />Harderto cache<br />Hardertoshard<br />Avoidthemwheneverpossible<br />
  15. 15. Caching<br />Validation:Consistentwith performance penalties 2 HTTP Headers: Etag (If-None-Match) and Last-Modified(If-Modified-Since)<br />Expiration:Fasterbuteventuallyinconsistent HTTP Header: Cache-Control: max-age=180, public<br />
  16. 16. Authentication != Authorization<br />Authentication:<br />Confirmuseridentitywiththerightcredentials (pwd)<br />Handledby MELI Plugins<br />Authorization:<br />Usermayperformthisaction (updatelistingtitle)<br />Handledbythedeveloper<br />
  17. 17. Authentication<br />MELI adoptedtheOAuth 2.0 standard<br />3 actors: MELI, Applications and Users (ResourceOwners)<br />OAuthallowsApplicationstoperformactionsonbehalf of Users<br />whithoutaccesstotheircredentials (pwd)<br />Example<br />
  18. 18. Avoidmultipleowners<br />A resourceshouldhaveonly 2 “views”:<br />Public<br />Private (alwaysfromtheowner)<br />GET /users/123?caller_id=456 (456 bougthanitemfrom 123)<br />-> Denied! Caller_idmust be theowner of theresource.Sellerinformationwill be exposedthroughan ORDER resource<br />PUT /items/MLA6781?caller.id=123(makethe status of theitem “inactive”)<br />-> Denied! Denied! Caller_idmust be theowner of theresource. Ownerscan´tchangethe status. A differentservicemust be createdforthis (adminservice)<br />
  19. 19. Business Rules are part of the API<br />PricingAPIscould be consumedby SYI, FAQs, etc<br />
  20. 20. Resourcesmust be shardable<br />Scalingout, notup<br />Eg: Multigetsmakesharding more difficult<br />
  21. 21. Embrace inconsistency<br /><ul><li> Brewster’s CAP Theorem (Consitency, Availability, Partition Tolerance; pick 2)
  22. 22. Actual trade-off is A vs C.
  23. 23. 99% of the cases we´ll pick A+P
  24. 24. No more A[C]ID properties
  25. 25. Embraceinconsistency -> Eventual consistency</li></li></ul><li>HTTP waytooptimisticlocking<br /><ul><li>GET /users/123
  26. 26. Etag = ABC
  27. 27. POST /users/123 (performonlyIf-match: ABC)-> No-oneelse has modifiedtheobject</li></ul>If-match header<br />
  28. 28. An API shouldhandlebasic CRUD<br />Make PUSH notificationsavilable<br />Complexqueries are notanResource API Developerresponsibility<br />Provide “push” streaming<br />
  29. 29. FrontEndsshouldhandle “state”<br />Granular, Atomic & Stateless<br />User<br />SYIFrontEnd<br />ItemsAPI<br />A differentversion ofSYI maytake a differentnumber of steps<br />SelectCategory<br />ItemDetails<br />ListingTypes<br />The “final call”remainsthesame<br />Confirmation<br />POST Item<br />
  30. 30. Granularityis a designchoice<br />Posting a new Listingrequires 3 steps:<br />POST /pictures<br />POST /items<br />POST /items/X/descriptions<br />There *are* exceptions<br />
  31. 31. 201: ObjectCreated<br />206: Partiallycreated (complete paymenttocreateit)<br />401: Unauthorized<br />404: Notfound<br />410: Gone<br />500: Internal Server Error<br />501: Notimplemented<br />HTTP codesare part of the API<br />
  32. 32. Makeyour API usable<br />Use standard HTTP Verbs<br />Selfdocumentyour API (OPTIONS Verb)<br />ProvideSelection & Multiget (onlyifneccessary)<br />ProvideSearch & Pagination (onlyifneccesary)<br />Avoidmultipleowners<br />Embrace inconsistency<br />Use if-match tohandleoptimisticlocking<br />Handle Basic CRUD & provide “push” streaming<br />Makeyourresourcesshardable<br />Maye API calls granular, atomic & stateless<br />HTTP returncodes are part of the API<br />Wrapping up…<br />
  33. 33. API Designchoices<br />Thankyou! <br />@drabinovich<br />

×