1. API Designchoices @drabinovich

2. REST on top of HTTP Organizeeverythingaround“Resources”https://api.mercadolibre.com/sites/MLA https://api.mercadolibre.com/users/4605484

3. Use standard HTTP Verbs PUT /users/4605484 {last_name: “Fagúndez” }

5. “seller_id” vs “customer_id” (avoid the DOCS check)

6. “condition: used” over “used:true” (scalable!)

7. Design for canonical cases (de-normalize wisely)

9. AutomaticPretty-Print PerformingGETsfrom a Browser

10. ProvideSelection Choosethefieldsto be returned /items/MLA121484389?attributes=title { title: "Boomerang Artesanales De Alta Calidad - Exclusivos -" }

11. Multiget Get N resources at once /items?ids=MLA121484389,MLA125002468&attributes=title [ -{ title: "Boomerang De Diseño Australiano Con Retorno Garantizado" } -{ title: "Boomerang Artesanales De Alta Calidad – Exclusivos" } ]

12. Searchonresources Complexquerieson a resource /users/search?nickname=LEWIS_CARROLL

13. Pagination Managelargeresultsets /sites/MLA/search?q=boomerang&limit=2&offset=10

14. Thereis no free lunch Selection, Multiget, Search are REST violationswithhiddencosts Harderto cache Hardertoshard Avoidthemwheneverpossible

15. Caching Validation:Consistentwith performance penalties 2 HTTP Headers: Etag (If-None-Match) and Last-Modified(If-Modified-Since) Expiration:Fasterbuteventuallyinconsistent HTTP Header: Cache-Control: max-age=180, public

16. Authentication != Authorization Authentication: Confirmuseridentitywiththerightcredentials (pwd) Handledby MELI Plugins Authorization: Usermayperformthisaction (updatelistingtitle) Handledbythedeveloper

17. Authentication MELI adoptedtheOAuth 2.0 standard 3 actors: MELI, Applications and Users (ResourceOwners) OAuthallowsApplicationstoperformactionsonbehalf of Users whithoutaccesstotheircredentials (pwd) Example

18. Avoidmultipleowners A resourceshouldhaveonly 2 “views”: Public Private (alwaysfromtheowner) GET /users/123?caller_id=456 (456 bougthanitemfrom 123) -> Denied! Caller_idmust be theowner of theresource.Sellerinformationwill be exposedthroughan ORDER resource PUT /items/MLA6781?caller.id=123(makethe status of theitem “inactive”) -> Denied! Denied! Caller_idmust be theowner of theresource. Ownerscan´tchangethe status. A differentservicemust be createdforthis (adminservice)

19. Business Rules are part of the API PricingAPIscould be consumedby SYI, FAQs, etc

20. Resourcesmust be shardable Scalingout, notup Eg: Multigetsmakesharding more difficult

22. Actual trade-off is A vs C.

23. 99% of the cases we´ll pick A+P

24. No more A[C]ID properties

26. Etag = ABC

27. POST /users/123 (performonlyIf-match: ABC)-> No-oneelse has modifiedtheobjectIf-match header

28. An API shouldhandlebasic CRUD Make PUSH notificationsavilable Complexqueries are notanResource API Developerresponsibility Provide “push” streaming

29. FrontEndsshouldhandle “state” Granular, Atomic & Stateless User SYIFrontEnd ItemsAPI A differentversion ofSYI maytake a differentnumber of steps SelectCategory ItemDetails ListingTypes The “final call”remainsthesame Confirmation POST Item

30. Granularityis a designchoice Posting a new Listingrequires 3 steps: POST /pictures POST /items POST /items/X/descriptions There *are* exceptions

31. 201: ObjectCreated 206: Partiallycreated (complete paymenttocreateit) 401: Unauthorized 404: Notfound 410: Gone 500: Internal Server Error 501: Notimplemented HTTP codesare part of the API

32. Makeyour API usable Use standard HTTP Verbs Selfdocumentyour API (OPTIONS Verb) ProvideSelection & Multiget (onlyifneccessary) ProvideSearch & Pagination (onlyifneccesary) Avoidmultipleowners Embrace inconsistency Use if-match tohandleoptimisticlocking Handle Basic CRUD & provide “push” streaming Makeyourresourcesshardable Maye API calls granular, atomic & stateless HTTP returncodes are part of the API Wrapping up…

33. API Designchoices Thankyou! @drabinovich