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

designimplementationdeploymentscalingretirement

API

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 @itnig