Date post: | 18-Dec-2014 |
Category: |
Technology |
Upload: | daniel-rabinovich |
View: | 3,145 times |
Download: | 0 times |
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…