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.

Transcript

1. API design and more
3. github.com/jrom @jordiromero Jordi Romero
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