API Design choices

API Designchoices
@drabinovich

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

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

Makeyour 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)

ProvideIntrospection
Getmetadatausing STD HTTP “Options” Verb
OPTIONS /sites/MLA
https://api.mercadolibre.com/sites/MLA

AutomaticPretty-Print
PerformingGETsfrom a Browser

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

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"
}
]

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

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

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

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

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

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

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)

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

Resourcesmust be shardable
Scalingout, notup
Eg: Multigetsmakesharding more difficult

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
Embraceinconsistency -> Eventual consistency

HTTP waytooptimisticlocking
GET /users/123
Etag = ABC
POST /users/123 (performonlyIf-match: ABC)-> No-oneelse has modifiedtheobject
If-match header

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

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

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

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

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…

API Designchoices
Thankyou!
@drabinovich

https://twitter.com	34
https://twimg0-a.akamaihd.net	1
https://si0.twimg.com	1
http://www.mashup.or.kr	1
https://www.facebook.com	1

API Design choices

by Daniel Rabinovich

Accessibility

Categories

Upload Details

Usage Rights

5 Embeds 38

Statistics