we want APIs that are easy
to understand, consume,
extend and scale
Slide 10
Slide 10 text
design
implementation
deployment
scaling
API
Slide 11
Slide 11 text
design
implementation
deployment
scaling
API
REAL SCALE
Slide 12
Slide 12 text
#protip
document it first
Slide 13
Slide 13 text
alternative
throw v1 as soon as you finish it
Slide 14
Slide 14 text
design
implementation
deployment
scaling
API
Slide 15
Slide 15 text
HTTP REST URI METHODS
STATUS METADATA
REPRESENTATION SECURITY
VERSIONING PAGINATION
Slide 16
Slide 16 text
HTTP
HyperText Transfer Protocol - OSI lvl 7
learn to love it
use proper URIs, methods, status codes, request
and response headers, ...
Slide 17
Slide 17 text
REST
REpresentational State Transfer
Resources are first class citizens
Resources have unique representations
Communication is stateless
Slide 18
Slide 18 text
URI
Uniform Resource Identifier
scheme://authority/path?query#fragment
http://api.sports.com/sports/soccer/teams/
fcbarcelona/players?max_age=24
Slide 19
Slide 19 text
URIs are resource
identifiers
not just a path to a server action
Slide 20
Slide 20 text
BAD URIs
http://toster.ru/posts/
http://toster.ru/posts/first_post
http://toster.ru/posts/Hello
http://toster.ru/posts.json
Slide 21
Slide 21 text
BAD URIs
http://toster.ru/posts/
http://toster.ru/posts/first_post
http://toster.ru/posts/Hello
http://toster.ru/posts.json
trailing slash
file extension
upper case
underscore
Slide 22
Slide 22 text
GOOD URIs
http://toster.ru/blogs/jordi/posts/api-design
http://toster.ru/blogs/jordi/posts
http://toster.ru/blogs/jordi
http://toster.ru/blogs
Slide 23
Slide 23 text
GOOD URIs
http://toster.ru/blogs/jordi/posts/api-design
http://toster.ru/blogs/jordi/posts
http://toster.ru/blogs/jordi
http://toster.ru/blogs hierarchical
resource identifier
I see what you did there
Slide 24
Slide 24 text
HTTP methods
GET POST PUT DELETE HEAD PATCH ...
Also called “Verbs”
Together with a URI they tell the API what to do
Slide 25
Slide 25 text
GET
HEAD
PUT
POST
DELETE
PATCH
retrieve a resource representation
get only the headers, no body
update a resource
create a resource, execute controllers
remove a resource
partially update a resource
more...
Slide 26
Slide 26 text
Response statuses
1xx 2xx 3xx 4xx 5xx
Do not limit to 200, 404 and 500
RTFM Specifications
Slide 27
Slide 27 text
Metadata
Useful req/res information in the headers
Content-Type
Content-Length
Last-Modified
Etag
Location
Cache-Control
Expires
Date
Pragma
Custom, ...
Slide 28
Slide 28 text
Metadata
Useful req/res information in the headers
Content-Type
Content-Length
Last-Modified
Etag
Location
Cache-Control
Expires
Date
Pragma
Custom, ...
MORE ON THAT LATER
Slide 29
Slide 29 text
Security
Protect private resources
OAuth is the most common option right now
Basic HTTP Authentication also works
SSL is not optional
Slide 30
Slide 30 text
Versioning
APIs should evolve without breaking
example.com/api/v3/posts BAD
v3.api.example.com/posts OK
Accept: application/vnd.example.v3+json GOOD
Slide 31
Slide 31 text
Pagination
Return a partial collection
example.com/posts/pages/2 BAD
example.com/posts?page=2&per_page=20 GOOD
do only what’s critical while
building a response.
everything else must be async
Slide 38
Slide 38 text
design
implementation
deployment
scaling
API
Slide 39
Slide 39 text
stateless processes
any process is good
Sessions can go to Redis, Memcached, ...
State must go on stateful processes (database)
Slide 40
Slide 40 text
disposable processes
license to kill’em
Processes being stateless and disposable, it’s easy
to avoid memory bloat and scale out
Slide 41
Slide 41 text
structured processes
app servers, workers, web servers, ...
It’s important to separate processes by their
primary task
Slide 42
Slide 42 text
design
implementation
deployment
scaling
API
Slide 43
Slide 43 text
horizontal scaling
is inexpensive
If more load can be handled by more processes
Slide 44
Slide 44 text
horizontal scaling
is inexpensive not really
If more load can be handled by more processes:
it scales!
Slide 45
Slide 45 text
application caching
don’t do things twice
Never calculate things twice. Do it once, store it.
Redis, Memcached, I’m looking at you.
Slide 46
Slide 46 text
HTTP caching
save bandwidth, cut response time
Use HTTP headers to define the response’s
cacheability, expiration, validity, ...
Take advantage of Varnish, Squid, ...
Slide 47
Slide 47 text
database replication
faster reads is a big win
If your API serves more reads than writes, send the
reads to read-only slaves of the database
Slide 48
Slide 48 text
delay async tasks
response time is everything
If you didn’t before,
do it now