APIdesign and more
Jordi Romerogithub.com/jrom@jordiromero
API
ApplicationProgrammingInterface
web   APIREST
we want APIs that are easyto understand, consume,extend and scale
designAPI  implementation  deployment  scaling
designAPI  implementation  deployment  scaling  retirement
design         SCA LE R EALAPI               implementation                  deployment                  scaling
#protipdocument it first
alternativethrow v1 as soon as you finish it
designAPI  implementation  deployment  scaling
HTTP REST URI METHODSSTATUS METADATAREPRESENTATION SECURITYVERSIONING PAGINATION
HTTPHyperText Transfer Protocol - OSI lvl 7learn to love ituse proper URIs, methods, status codes, requestand response hea...
RESTREpresentational State TransferResources are first class citizensResources have unique representationsCommunication is...
URIUniform Resource Identifierscheme://authority/path?query#fragmenthttp://api.sports.com/sports/soccer/teams/fcbarcelona/...
URIs are resourceidentifiersnot just a path to a server action
BAD URIshttp://toster.ru/posts/http://toster.ru/posts/first_posthttp://toster.ru/posts/Hellohttp://toster.ru/posts.json
BAD URIshttp://toster.ru/posts/http://toster.ru/posts/first_post                                 trailing slash           ...
GOOD URIshttp://toster.ru/blogs/jordi/posts/api-designhttp://toster.ru/blogs/jordi/postshttp://toster.ru/blogs/jordihttp:/...
GOOD URIshttp://toster.ru/blogs/jordi/posts/api-designhttp://toster.ru/blogs/jordi/postshttp://toster.ru/blogs/jordihttp:/...
HTTP methodsGET POST PUT DELETE HEAD PATCH ...Also called “Verbs”Together with a URI they tell the API what to do
GET          retrieve a resource representation  HEAD get only the headers, no body   PUT update a resource  POST create a...
Response statuses1xx 2xx 3xx 4xx 5xxDo not limit to 200, 404 and 500RTFM Specifications
MetadataUseful req/res information in the headersContent-Type          Cache-ControlContent-Length        ExpiresLast-Modi...
MetadataUseful req/res information in the headersContent-Type             Cache-ControlContent-Length           Expires   ...
SecurityProtect private resourcesOAuth is the most common option right nowBasic HTTP Authentication also worksSSL is not o...
VersioningAPIs should evolve without breakingexample.com/api/v3/posts BADv3.api.example.com/posts OKAccept: application/vn...
PaginationReturn a partial collectionexample.com/posts/pages/2 BADexample.com/posts?page=2&per_page=20 GOOD
designAPI  implementation  deployment  scaling
code!
code!ideally with BDD
Ruby on RailsSinatra — Rubyexpress — node.js∞ options...
abstract the backing servicesas much as possible
do only what’s critical whilebuilding a response.everything else must be async
designAPI  implementation  deployment  scaling
stateless processesany process is goodSessions can go to Redis, Memcached, ...State must go on stateful processes (database)
disposable processeslicense to kill’emProcesses being stateless and disposable, it’s easyto avoid memory bloat and scale out
structured processesapp servers, workers, web servers, ...It’s important to separate processes by theirprimary task
designAPI  implementation  deployment  scaling
horizontal scalingis inexpensiveIf more load can be handled by more processes
horizontal scalingis inexpensive not reallyIf more load can be handled by more processes:it scales!
application cachingdon’t do things twiceNever calculate things twice. Do it once, store it.Redis, Memcached, I’m looking a...
HTTP cachingsave bandwidth, cut response timeUse HTTP headers to define the response’scacheability, expiration, validity, ...
database replicationfaster reads is a big winIf your API serves more reads than writes, send thereads to read-only slaves ...
delay async tasksresponse time is everythingIf you didn’t before,do it now
designAPI  implementation  deployment  scaling
APIdesign and more
thankyou
thank youспасибо
slides available atjrom.net/api-design-and-more
Jordi Romerofollow @jordiromerofollow @itnig
Api Design and More (Friday Training at Itnig)
Api Design and More (Friday Training at Itnig)
Api Design and More (Friday Training at Itnig)
Upcoming SlideShare
Loading in …5
×

Api Design and More (Friday Training at Itnig)

1,028 views

Published on

Friday Training by Jordi Romero about the challenges of creating an API for Teambox

0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,028
On SlideShare
0
From Embeds
0
Number of Embeds
11
Actions
Shares
0
Downloads
13
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

Api Design and More (Friday Training at Itnig)

  1. 1. APIdesign and more
  2. 2. Jordi Romerogithub.com/jrom@jordiromero
  3. 3. API
  4. 4. ApplicationProgrammingInterface
  5. 5. web APIREST
  6. 6. we want APIs that are easyto understand, consume,extend and scale
  7. 7. designAPI implementation deployment scaling
  8. 8. designAPI implementation deployment scaling retirement
  9. 9. design SCA LE R EALAPI implementation deployment scaling
  10. 10. #protipdocument it first
  11. 11. alternativethrow v1 as soon as you finish it
  12. 12. designAPI implementation deployment scaling
  13. 13. HTTP REST URI METHODSSTATUS METADATAREPRESENTATION SECURITYVERSIONING PAGINATION
  14. 14. HTTPHyperText Transfer Protocol - OSI lvl 7learn to love ituse proper URIs, methods, status codes, requestand response headers, ...
  15. 15. RESTREpresentational State TransferResources are first class citizensResources have unique representationsCommunication is stateless
  16. 16. URIUniform Resource Identifierscheme://authority/path?query#fragmenthttp://api.sports.com/sports/soccer/teams/fcbarcelona/players?max_age=24
  17. 17. URIs are resourceidentifiersnot just a path to a server action
  18. 18. BAD URIshttp://toster.ru/posts/http://toster.ru/posts/first_posthttp://toster.ru/posts/Hellohttp://toster.ru/posts.json
  19. 19. BAD URIshttp://toster.ru/posts/http://toster.ru/posts/first_post trailing slash underscorehttp://toster.ru/posts/Hello upper casehttp://toster.ru/posts.json file extension
  20. 20. GOOD URIshttp://toster.ru/blogs/jordi/posts/api-designhttp://toster.ru/blogs/jordi/postshttp://toster.ru/blogs/jordihttp://toster.ru/blogs
  21. 21. GOOD URIshttp://toster.ru/blogs/jordi/posts/api-designhttp://toster.ru/blogs/jordi/postshttp://toster.ru/blogs/jordihttp://toster.ru/blogs hierarchical resource identifier I see what you did there
  22. 22. HTTP methodsGET POST PUT DELETE HEAD PATCH ...Also called “Verbs”Together with a URI they tell the API what to do
  23. 23. GET retrieve a resource representation HEAD get only the headers, no body PUT update a resource POST create a resource, execute controllersDELETE remove a resource PATCH partially update a resource more...
  24. 24. Response statuses1xx 2xx 3xx 4xx 5xxDo not limit to 200, 404 and 500RTFM Specifications
  25. 25. MetadataUseful req/res information in the headersContent-Type Cache-ControlContent-Length ExpiresLast-Modified DateEtag PragmaLocation Custom, ...
  26. 26. MetadataUseful req/res information in the headersContent-Type Cache-ControlContent-Length Expires ER LAT AT DateLast-Modified E ON THEtag M OR PragmaLocation Custom, ...
  27. 27. SecurityProtect private resourcesOAuth is the most common option right nowBasic HTTP Authentication also worksSSL is not optional
  28. 28. VersioningAPIs should evolve without breakingexample.com/api/v3/posts BADv3.api.example.com/posts OKAccept: application/vnd.example.v3+json GOOD
  29. 29. PaginationReturn a partial collectionexample.com/posts/pages/2 BADexample.com/posts?page=2&per_page=20 GOOD
  30. 30. designAPI implementation deployment scaling
  31. 31. code!
  32. 32. code!ideally with BDD
  33. 33. Ruby on RailsSinatra — Rubyexpress — node.js∞ options...
  34. 34. abstract the backing servicesas much as possible
  35. 35. do only what’s critical whilebuilding a response.everything else must be async
  36. 36. designAPI implementation deployment scaling
  37. 37. stateless processesany process is goodSessions can go to Redis, Memcached, ...State must go on stateful processes (database)
  38. 38. disposable processeslicense to kill’emProcesses being stateless and disposable, it’s easyto avoid memory bloat and scale out
  39. 39. structured processesapp servers, workers, web servers, ...It’s important to separate processes by theirprimary task
  40. 40. designAPI implementation deployment scaling
  41. 41. horizontal scalingis inexpensiveIf more load can be handled by more processes
  42. 42. horizontal scalingis inexpensive not reallyIf more load can be handled by more processes:it scales!
  43. 43. application cachingdon’t do things twiceNever calculate things twice. Do it once, store it.Redis, Memcached, I’m looking at you.
  44. 44. HTTP cachingsave bandwidth, cut response timeUse HTTP headers to define the response’scacheability, expiration, validity, ...Take advantage of Varnish, Squid, ...
  45. 45. database replicationfaster reads is a big winIf your API serves more reads than writes, send thereads to read-only slaves of the database
  46. 46. delay async tasksresponse time is everythingIf you didn’t before,do it now
  47. 47. designAPI implementation deployment scaling
  48. 48. APIdesign and more
  49. 49. thankyou
  50. 50. thank youспасибо
  51. 51. slides available atjrom.net/api-design-and-more
  52. 52. Jordi Romerofollow @jordiromerofollow @itnig

×