API Design choices

@drabinovich

REST on top of HTTP

Organize everything around “Resources”

https://api.mercadolibre.com/sites/MLA https://api.mercadolibre.com/users/4605484

Use standard HTTP Verbs

PUT /users/4605484{

last_name: “Fagúndez”

}

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)

Provide Introspection

Get metadata using STD HTTP “Options” Verb

OPTIONS /sites/MLA

https://api.mercadolibre.com/sites/MLA

Automatic Pretty-Print

Performing GETs from a Browser

Provide Selection

Choose the fields to 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" }

]

Search on resources

Complex queries on a resource /users/search?nickname=LEWIS_CARROLL

Pagination

Manage large resultsets

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

There is no free lunch

Selection, Multiget, Searchare REST violations with hidden costs

Harder to cacheHarder to shard

Avoid them whenever possible

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

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

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

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)

Business Rules are part of the API

Pricing APIs could be consumed by SYI, FAQs, etc

Resources must be shardable

Scaling out, not up

Eg: Multigets make sharding 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

• Embrace inconsistency -> Eventual consistency

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

An API should handle basic CRUDMake PUSH notifications avilable

Complex queries are not an Resource API Developer responsibility

Provide “push” streaming

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

Granularity is a design choice

Posting a new Listing requires 3 steps:

1) POST /pictures2) POST /items3) POST /items/X/descriptions

There *are* exceptions

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

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…

API Design choices

Thank you! @drabinovich