API design and more

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