$30 off During Our Annual Pro Sale. View Details »

API design and more

Jordi Romero
December 02, 2011

API design and more

Talk about API design, implementation, deployment and scaling, with special emphasis on the design. Go grab a beer and enjoy the presentation :)

API Design http://jrom.net/api-design-and-more post including video of the talk.

Jordi Romero

December 02, 2011
Tweet

More Decks by Jordi Romero

Other Decks in Programming

Transcript

  1. API
    design and more

    View Slide

  2. View Slide

  3. github.com/jrom
    @jordiromero
    Jordi Romero

    View Slide

  4. View Slide

  5. View Slide

  6. API

    View Slide

  7. Application
    Programming
    Interface

    View Slide

  8. API
    web
    REST

    View Slide

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

    View Slide

  10. design
    implementation
    deployment
    scaling
    API

    View Slide

  11. design
    implementation
    deployment
    scaling
    API
    REAL SCALE

    View Slide

  12. #protip
    document it first

    View Slide

  13. alternative
    throw v1 as soon as you finish it

    View Slide

  14. design
    implementation
    deployment
    scaling
    API

    View Slide

  15. HTTP REST URI METHODS
    STATUS METADATA
    REPRESENTATION SECURITY
    VERSIONING PAGINATION

    View Slide

  16. HTTP
    HyperText Transfer Protocol - OSI lvl 7
    learn to love it
    use proper URIs, methods, status codes, request
    and response headers, ...

    View Slide

  17. REST
    REpresentational State Transfer
    Resources are first class citizens
    Resources have unique representations
    Communication is stateless

    View Slide

  18. URI
    Uniform Resource Identifier
    scheme://authority/path?query#fragment
    http://api.sports.com/sports/soccer/teams/
    fcbarcelona/players?max_age=24

    View Slide

  19. URIs are resource
    identifiers
    not just a path to a server action

    View Slide

  20. BAD URIs
    http://toster.ru/posts/
    http://toster.ru/posts/first_post
    http://toster.ru/posts/Hello
    http://toster.ru/posts.json

    View Slide

  21. 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

    View Slide

  22. 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

    View Slide

  23. 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

    View Slide

  24. HTTP methods
    GET POST PUT DELETE HEAD PATCH ...
    Also called “Verbs”
    Together with a URI they tell the API what to do

    View Slide

  25. 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...

    View Slide

  26. Response statuses
    1xx 2xx 3xx 4xx 5xx
    Do not limit to 200, 404 and 500
    RTFM Specifications

    View Slide

  27. Metadata
    Useful req/res information in the headers
    Content-Type
    Content-Length
    Last-Modified
    Etag
    Location
    Cache-Control
    Expires
    Date
    Pragma
    Custom, ...

    View Slide

  28. 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

    View Slide

  29. Security
    Protect private resources
    OAuth is the most common option right now
    Basic HTTP Authentication also works
    SSL is not optional

    View Slide

  30. 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

    View Slide

  31. Pagination
    Return a partial collection
    example.com/posts/pages/2 BAD
    example.com/posts?page=2&per_page=20 GOOD

    View Slide

  32. design
    implementation
    deployment
    scaling
    API

    View Slide

  33. code!

    View Slide

  34. code!
    ideally with BDD

    View Slide

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

    View Slide

  36. abstract the backing services
    as much as possible

    View Slide

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

    View Slide

  38. design
    implementation
    deployment
    scaling
    API

    View Slide

  39. stateless processes
    any process is good
    Sessions can go to Redis, Memcached, ...
    State must go on stateful processes (database)

    View Slide

  40. disposable processes
    license to kill’em
    Processes being stateless and disposable, it’s easy
    to avoid memory bloat and scale out

    View Slide

  41. structured processes
    app servers, workers, web servers, ...
    It’s important to separate processes by their
    primary task

    View Slide

  42. design
    implementation
    deployment
    scaling
    API

    View Slide

  43. horizontal scaling
    is inexpensive
    If more load can be handled by more processes

    View Slide

  44. horizontal scaling
    is inexpensive not really
    If more load can be handled by more processes:
    it scales!

    View Slide

  45. application caching
    don’t do things twice
    Never calculate things twice. Do it once, store it.
    Redis, Memcached, I’m looking at you.

    View Slide

  46. HTTP caching
    save bandwidth, cut response time
    Use HTTP headers to define the response’s
    cacheability, expiration, validity, ...
    Take advantage of Varnish, Squid, ...

    View Slide

  47. 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

    View Slide

  48. delay async tasks
    response time is everything
    If you didn’t before,
    do it now

    View Slide

  49. design
    implementation
    deployment
    scaling
    API

    View Slide

  50. API
    design and more

    View Slide

  51. thank
    you

    View Slide

  52. thank
    you
    спасибо

    View Slide

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

    View Slide

  54. signup at
    teambox.com

    View Slide

  55. Jordi Romero
    follow @jordiromero
    follow @teambox_app

    View Slide