api design choices
DESCRIPTION
TRANSCRIPT
![Page 2: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/2.jpg)
REST on top of HTTP
Organize everything around “Resources”
https://api.mercadolibre.com/sites/MLA https://api.mercadolibre.com/users/4605484
![Page 3: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/3.jpg)
Use standard HTTP Verbs
PUT /users/4605484{
last_name: “Fagúndez”
}
![Page 4: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/4.jpg)
Make your API usable
APIs exist *not only* for machines
Conventions are key to a great usability.
• “AR” vs “0001” (ISO codes over proprietary codes)
• “seller_id” vs “customer_id” (avoid the DOCS check)
• “condition: used” over “used:true” (scalable!)
• Design for canonical cases (de-normalize wisely)
• Perform API Usability testing (subjects are developers)
![Page 5: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/5.jpg)
Provide Introspection
Get metadata using STD HTTP “Options” Verb
OPTIONS /sites/MLA
https://api.mercadolibre.com/sites/MLA
![Page 6: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/6.jpg)
Automatic Pretty-Print
Performing GETs from a Browser
![Page 7: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/7.jpg)
Provide Selection
Choose the fields to be returned
/items/MLA121484389?attributes=title
{title: "Boomerang Artesanales De Alta Calidad - Exclusivos -"}
![Page 8: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/8.jpg)
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" }
]
![Page 9: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/9.jpg)
Search on resources
Complex queries on a resource /users/search?nickname=LEWIS_CARROLL
![Page 10: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/10.jpg)
Pagination
Manage large resultsets
/sites/MLA/search?q=boomerang&limit=2&offset=10
![Page 11: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/11.jpg)
There is no free lunch
Selection, Multiget, Searchare REST violations with hidden costs
Harder to cacheHarder to shard
Avoid them whenever possible
![Page 12: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/12.jpg)
Caching
• Validation: Consistent with performance penalties 2 HTTP Headers: Etag (If-None-Match) and Last-Modified(If-Modified-Since)
• Expiration: Faster but eventually inconsistent HTTP Header: Cache-Control: max-age=180, public
![Page 13: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/13.jpg)
Authentication != Authorization
Authentication:Confirm user identity with the right credentials
(pwd)Handled by MELI Plugins
Authorization:User may perform this action (update listing title)Handled by the developer
![Page 14: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/14.jpg)
Authentication
MELI adopted the OAuth 2.0 standard
3 actors: MELI, Applications and Users (Resource Owners)
OAuth allows Applications to perform actions on behalf of Users
whithout access to their credentials (pwd)
Example
![Page 15: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/15.jpg)
Avoid multiple owners
A resource should have only 2 “views”:a) Publicb) Private (always from the owner)
GET /users/123?caller_id=456 (456 bougth an item from 123)-> Denied! Caller_id must be the owner of the resource. Seller information will be exposed through an ORDER resource
PUT /items/MLA6781?caller.id=123 (make the status of the item “inactive”)-> Denied! Denied! Caller_id must be the owner of the resource. Owners can´t change the status. A different service must be created for this (admin service)
![Page 16: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/16.jpg)
Business Rules are part of the API
Pricing APIs could be consumed by SYI, FAQs, etc
![Page 17: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/17.jpg)
Resources must be shardable
Scaling out, not up
Eg: Multigets make sharding more difficult
![Page 18: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/18.jpg)
Embrace inconsistency
• Brewster’s CAP Theorem (Consitency, Availability, Partition Tolerance; pick 2)
• Actual trade-off is A vs C.
• 99% of the cases we´ll pick A+P
• No more A[C]ID properties
• Embrace inconsistency -> Eventual consistency
![Page 19: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/19.jpg)
HTTP way to optimistic locking
- GET /users/123- Etag = ABC
- POST /users/123 (perform only If-match: ABC)-> No-one else has modified the object
If-match header
![Page 20: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/20.jpg)
An API should handle basic CRUDMake PUSH notifications avilable
Complex queries are not an Resource API Developer responsibility
Provide “push” streaming
![Page 21: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/21.jpg)
FrontEnds should handle “state”
Granular, Atomic & Stateless
UserSYI
FrontEndItemsAPI
Select Category
Item Details
Listing Types
Confirmation
POST Item
A different version ofSYI may take a different
number of steps
The “final call”remains the same
![Page 22: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/22.jpg)
Granularity is a design choice
Posting a new Listing requires 3 steps:
1) POST /pictures2) POST /items3) POST /items/X/descriptions
There *are* exceptions
![Page 23: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/23.jpg)
201: Object Created206: Partially created (complete payment to create it)
401: Unauthorized404: Not found410: Gone
500: Internal Server Error501: Not implemented
HTTP codes are part of the API
![Page 24: API Design choices](https://reader033.vdocuments.mx/reader033/viewer/2022061211/5493083bb47959744d8b4762/html5/thumbnails/24.jpg)
Make your API usableUse standard HTTP VerbsSelf document your API (OPTIONS Verb)Provide Selection & Multiget (only if neccessary)Provide Search & Pagination (only if neccesary)Avoid multiple ownersEmbrace inconsistencyUse if-match to handle optimistic lockingHandle Basic CRUD & provide “push” streamingMake your resources shardableMaye API calls granular, atomic & statelessHTTP return codes are part of the API
Wrapping up…