jordi romero api for-the-mobile-era
TRANSCRIPT
APIdesign and more
github.com/jrom@jordiromero
Jordi Romero
API
Application Programming Interface
APIwebREST
we want APIs that are easy to understand, consume, extend and scale
designimplementationdeploymentscalingAPI
designimplementationdeploymentscaling
APIREAL SCALE
#protipdocument it first
alternativethrow v1 as soon as you finish it
designimplementationdeploymentscalingAPI
HTTP REST URI METHODS STATUS METADATA REPRESENTATION SECURITY VERSIONING PAGINATION
HTTPHyperText Transfer Protocol - OSI lvl 7
learn to love it
use proper URIs, methods, status codes, request and response headers, ...
RESTREpresentational State Transfer
Resources are first class citizensResources have unique representationsCommunication is stateless
URIUniform Resource Identifier
scheme://authority/path?query#fragment
http://api.sports.com/sports/soccer/teams/fcbarcelona/players?max_age=24
URIs are resource
identifiersnot just a path to a server action
BAD URIshttp://toster.ru/posts/http://toster.ru/posts/first_posthttp://toster.ru/posts/Hellohttp://toster.ru/posts.json
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
GOOD URIshttp://toster.ru/blogs/jordi/posts/api-designhttp://toster.ru/blogs/jordi/postshttp://toster.ru/blogs/jordihttp://toster.ru/blogs
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
HTTP methodsGET POST PUT DELETE HEAD PATCH ...
Also called “Verbs”
Together with a URI they tell the API what to do
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...
Response statuses1xx 2xx 3xx 4xx 5xx
Do not limit to 200, 404 and 500RTFM Specifications
MetadataUseful req/res information in the headers
Content-TypeContent-LengthLast-ModifiedEtagLocation
Cache-ControlExpiresDatePragmaCustom, ...
MetadataUseful req/res information in the headers
Content-TypeContent-LengthLast-ModifiedEtagLocation
Cache-ControlExpiresDatePragmaCustom, ...
MORE ON THAT LATER
SecurityProtect private resources
OAuth is the most common option right nowBasic HTTP Authentication also worksSSL is not optional
VersioningAPIs should evolve without breaking
example.com/api/v3/posts BADv3.api.example.com/posts OK
Accept: application/vnd.example.v3+json GOOD
PaginationReturn a partial collection
example.com/posts/pages/2 BADexample.com/posts?page=2&per_page=20 GOOD
designimplementationdeploymentscalingAPI
code!
code!ideally with BDD
Ruby on RailsSinatra — Rubyexpress — node.js∞ options...
abstract the backing services as much as possible
do only what’s critical while building a response.everything else must be async
designimplementationdeploymentscalingAPI
stateless processesany process is good
Sessions can go to Redis, Memcached, ...State must go on stateful processes (database)
disposable processeslicense to kill’em
Processes being stateless and disposable, it’s easy to avoid memory bloat and scale out
structured processesapp servers, workers, web servers, ...
It’s important to separate processes by their primary task
designimplementationdeploymentscalingAPI
horizontal scalingis inexpensive
If more load can be handled by more processes
horizontal scalingis inexpensive not really
If more load can be handled by more processes:
it scales!
application cachingdon’t do things twice
Never calculate things twice. Do it once, store it.Redis, Memcached, I’m looking at you.
HTTP cachingsave bandwidth, cut response time
Use HTTP headers to define the response’s cacheability, expiration, validity, ...
Take advantage of Varnish, Squid, ...
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
delay async tasksresponse time is everything
If you didn’t before, do it now
designimplementationdeploymentscalingAPI
APIdesign and more
thank you
thank youспасибо
slides available atjrom.net/api-design-and-more
Jordi Romerofollow @jordiromerofollow @teambox_app