Slide 1

Slide 1 text

API design and more

Slide 2

Slide 2 text

No content

Slide 3

Slide 3 text

github.com/jrom @jordiromero Jordi Romero

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

API

Slide 7

Slide 7 text

Application Programming Interface

Slide 8

Slide 8 text

API web REST

Slide 9

Slide 9 text

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

Slide 32

Slide 32 text

design implementation deployment scaling API

Slide 33

Slide 33 text

code!

Slide 34

Slide 34 text

code! ideally with BDD

Slide 35

Slide 35 text

Ruby on Rails Sinatra — Ruby express — node.js ∞ options...

Slide 36

Slide 36 text

abstract the backing services as much as possible

Slide 37

Slide 37 text

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

Slide 49

Slide 49 text

design implementation deployment scaling API

Slide 50

Slide 50 text

API design and more

Slide 51

Slide 51 text

thank you

Slide 52

Slide 52 text

thank you спасибо

Slide 53

Slide 53 text

slides available at jrom.net/api-design-and-more

Slide 54

Slide 54 text

signup at teambox.com

Slide 55

Slide 55 text

Jordi Romero follow @jordiromero follow @teambox_app