jordi romero api for-the-mobile-era

55
API design and more

Upload: toster

Post on 09-May-2015

2.110 views

Category:

Technology


0 download

TRANSCRIPT

Page 1: Jordi Romero Api for-the-mobile-era

APIdesign and more

Page 2: Jordi Romero Api for-the-mobile-era
Page 4: Jordi Romero Api for-the-mobile-era
Page 5: Jordi Romero Api for-the-mobile-era
Page 6: Jordi Romero Api for-the-mobile-era

API

Page 7: Jordi Romero Api for-the-mobile-era

Application Programming Interface

Page 8: Jordi Romero Api for-the-mobile-era

APIwebREST

Page 9: Jordi Romero Api for-the-mobile-era

we want APIs that are easy to understand, consume, extend and scale

Page 10: Jordi Romero Api for-the-mobile-era

designimplementationdeploymentscalingAPI

Page 11: Jordi Romero Api for-the-mobile-era

designimplementationdeploymentscaling

APIREAL SCALE

Page 12: Jordi Romero Api for-the-mobile-era

#protipdocument it first

Page 13: Jordi Romero Api for-the-mobile-era

alternativethrow v1 as soon as you finish it

Page 14: Jordi Romero Api for-the-mobile-era

designimplementationdeploymentscalingAPI

Page 15: Jordi Romero Api for-the-mobile-era

HTTP REST URI METHODS STATUS METADATA REPRESENTATION SECURITY VERSIONING PAGINATION

Page 16: Jordi Romero Api for-the-mobile-era

HTTPHyperText Transfer Protocol - OSI lvl 7

learn to love it

use proper URIs, methods, status codes, request and response headers, ...

Page 17: Jordi Romero Api for-the-mobile-era

RESTREpresentational State Transfer

Resources are first class citizensResources have unique representationsCommunication is stateless

Page 18: Jordi Romero Api for-the-mobile-era

URIUniform Resource Identifier

scheme://authority/path?query#fragment

http://api.sports.com/sports/soccer/teams/fcbarcelona/players?max_age=24

Page 19: Jordi Romero Api for-the-mobile-era

URIs are resource

identifiersnot just a path to a server action

Page 20: Jordi Romero Api for-the-mobile-era

BAD URIshttp://toster.ru/posts/http://toster.ru/posts/first_posthttp://toster.ru/posts/Hellohttp://toster.ru/posts.json

Page 21: Jordi Romero Api for-the-mobile-era

BAD URIshttp://toster.ru/posts/http://toster.ru/posts/first_posthttp://toster.ru/posts/Hellohttp://toster.ru/posts.json

trailing slash

file extension

upper case

underscore

Page 22: Jordi Romero Api for-the-mobile-era

GOOD URIshttp://toster.ru/blogs/jordi/posts/api-designhttp://toster.ru/blogs/jordi/postshttp://toster.ru/blogs/jordihttp://toster.ru/blogs

Page 23: Jordi Romero Api for-the-mobile-era

GOOD URIshttp://toster.ru/blogs/jordi/posts/api-designhttp://toster.ru/blogs/jordi/postshttp://toster.ru/blogs/jordihttp://toster.ru/blogs hierarchical

resource identifierI see what you did there

Page 24: Jordi Romero Api for-the-mobile-era

HTTP methodsGET POST PUT DELETE HEAD PATCH ...

Also called “Verbs”

Together with a URI they tell the API what to do

Page 25: Jordi Romero Api for-the-mobile-era

GETHEAD

PUTPOST

DELETEPATCH

retrieve a resource representation

get only the headers, no body

update a resource

create a resource, execute controllers

remove a resource

partially update a resourcemore...

Page 26: Jordi Romero Api for-the-mobile-era

Response statuses1xx 2xx 3xx 4xx 5xx

Do not limit to 200, 404 and 500RTFM Specifications

Page 27: Jordi Romero Api for-the-mobile-era

MetadataUseful req/res information in the headers

Content-TypeContent-LengthLast-ModifiedEtagLocation

Cache-ControlExpiresDatePragmaCustom, ...

Page 28: Jordi Romero Api for-the-mobile-era

MetadataUseful req/res information in the headers

Content-TypeContent-LengthLast-ModifiedEtagLocation

Cache-ControlExpiresDatePragmaCustom, ...

MORE ON THAT LATER

Page 29: Jordi Romero Api for-the-mobile-era

SecurityProtect private resources

OAuth is the most common option right nowBasic HTTP Authentication also worksSSL is not optional

Page 30: Jordi Romero Api for-the-mobile-era

VersioningAPIs should evolve without breaking

example.com/api/v3/posts BADv3.api.example.com/posts OK

Accept: application/vnd.example.v3+json GOOD

Page 31: Jordi Romero Api for-the-mobile-era

PaginationReturn a partial collection

example.com/posts/pages/2 BADexample.com/posts?page=2&per_page=20 GOOD

Page 32: Jordi Romero Api for-the-mobile-era

designimplementationdeploymentscalingAPI

Page 33: Jordi Romero Api for-the-mobile-era

code!

Page 34: Jordi Romero Api for-the-mobile-era

code!ideally with BDD

Page 35: Jordi Romero Api for-the-mobile-era

Ruby on RailsSinatra — Rubyexpress — node.js∞ options...

Page 36: Jordi Romero Api for-the-mobile-era

abstract the backing services as much as possible

Page 37: Jordi Romero Api for-the-mobile-era

do only what’s critical while building a response.everything else must be async

Page 38: Jordi Romero Api for-the-mobile-era

designimplementationdeploymentscalingAPI

Page 39: Jordi Romero Api for-the-mobile-era

stateless processesany process is good

Sessions can go to Redis, Memcached, ...State must go on stateful processes (database)

Page 40: Jordi Romero Api for-the-mobile-era

disposable processeslicense to kill’em

Processes being stateless and disposable, it’s easy to avoid memory bloat and scale out

Page 41: Jordi Romero Api for-the-mobile-era

structured processesapp servers, workers, web servers, ...

It’s important to separate processes by their primary task

Page 42: Jordi Romero Api for-the-mobile-era

designimplementationdeploymentscalingAPI

Page 43: Jordi Romero Api for-the-mobile-era

horizontal scalingis inexpensive

If more load can be handled by more processes

Page 44: Jordi Romero Api for-the-mobile-era

horizontal scalingis inexpensive not really

If more load can be handled by more processes:

it scales!

Page 45: Jordi Romero Api for-the-mobile-era

application cachingdon’t do things twice

Never calculate things twice. Do it once, store it.Redis, Memcached, I’m looking at you.

Page 46: Jordi Romero Api for-the-mobile-era

HTTP cachingsave bandwidth, cut response time

Use HTTP headers to define the response’s cacheability, expiration, validity, ...

Take advantage of Varnish, Squid, ...

Page 47: Jordi Romero Api for-the-mobile-era

database replicationfaster reads is a big win

If your API serves more reads than writes, send the reads to read-only slaves of the database

Page 48: Jordi Romero Api for-the-mobile-era

delay async tasksresponse time is everything

If you didn’t before, do it now

Page 49: Jordi Romero Api for-the-mobile-era

designimplementationdeploymentscalingAPI

Page 50: Jordi Romero Api for-the-mobile-era

APIdesign and more

Page 51: Jordi Romero Api for-the-mobile-era

thank you

Page 52: Jordi Romero Api for-the-mobile-era

thank youспасибо

Page 53: Jordi Romero Api for-the-mobile-era

slides available atjrom.net/api-design-and-more

Page 54: Jordi Romero Api for-the-mobile-era

signup atteambox.com