Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

API Design choices

4,444 views

Published on

Published in: Technology, Design

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 />

×