API design and more

Transcript

1. API design and more

2. None

3. github.com/jrom @jordiromero Jordi Romero

4. None
5. None

6. API

7. Application Programming Interface

8. API web REST

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

   and scale

10. design implementation deployment scaling API

11. design implementation deployment scaling API REAL SCALE

12. #protip document it first

13. alternative throw v1 as soon as you finish it

14. design implementation deployment scaling API

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

16. HTTP HyperText Transfer Protocol - OSI lvl 7 learn to

    love it use proper URIs, methods, status codes, request and response headers, ...

17. REST REpresentational State Transfer Resources are first class citizens Resources

    have unique representations Communication is stateless

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

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

    server action

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

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

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

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

24. HTTP methods GET POST PUT DELETE HEAD PATCH ... Also

    called “Verbs” Together with a URI they tell the API what to do

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

26. Response statuses 1xx 2xx 3xx 4xx 5xx Do not limit

    to 200, 404 and 500 RTFM Specifications

27. Metadata Useful req/res information in the headers Content-Type Content-Length Last-Modified

    Etag Location Cache-Control Expires Date Pragma Custom, ...

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

29. Security Protect private resources OAuth is the most common option

    right now Basic HTTP Authentication also works SSL is not optional

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

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

32. design implementation deployment scaling API

33. code!

34. code! ideally with BDD

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

    options...

36. abstract the backing services as much as possible

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

    must be async

38. design implementation deployment scaling API

39. stateless processes any process is good Sessions can go to

    Redis, Memcached, ... State must go on stateful processes (database)

40. disposable processes license to kill’em Processes being stateless and disposable,

    it’s easy to avoid memory bloat and scale out

41. structured processes app servers, workers, web servers, ... It’s important

    to separate processes by their primary task

42. design implementation deployment scaling API

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

    by more processes

44. horizontal scaling is inexpensive not really If more load can

    be handled by more processes: it scales!

45. application caching don’t do things twice Never calculate things twice.

    Do it once, store it. Redis, Memcached, I’m looking at you.

46. HTTP caching save bandwidth, cut response time Use HTTP headers

    to define the response’s cacheability, expiration, validity, ... Take advantage of Varnish, Squid, ...

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

48. delay async tasks response time is everything If you didn’t

    before, do it now

49. design implementation deployment scaling API

50. API design and more

51. thank you

52. thank you спасибо

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

54. signup at teambox.com

55. Jordi Romero follow @jordiromero follow @teambox_app