Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

RESTful APIs: Promises & lies

6,418 views

Published on

Presented at djangocon 2011. Covers best practices for designing/ building RESTful APIs. Discusses the enhanced version of django-piston used by PBS Education.

Published in: Technology

RESTful APIs: Promises & lies

  1. 1. RESTful APIs Promises & Lies!
  2. 2. Tareque  (täreɪk)    
  3. 3. what  do  all  these  companies   have  in  common?  
  4. 4. they  thrive  in  their  business  using  APIs  
  5. 5. in  fact,  all  of  them  provide  RESTful  APIs  
  6. 6. all  of  them  secure  their  APIs  using  Oauth  
  7. 7. these  facts  are  not  coincidental  
  8. 8. these  companies  made  a  choice  
  9. 9. they  chose  to  do  their  APIs  right  
  10. 10. so  what  is  this  talk  about?  
  11. 11. it’s  about  Web  APIs  
  12. 12. it’s  about  how  we  build  APIs  nowadays  
  13. 13. nice  &  solid  
  14. 14. we  all  have  been  building  APIs  for  some  time  now  
  15. 15. till  this  date,  there  are  hardly  any  resource  available  
  16. 16. that  tell  you  how  to  build  APIs  right  
  17. 17. standards  
  18. 18. best  practices  
  19. 19. we  all  learn  them  hard  way  
  20. 20. +  
  21. 21. =  magical  API  
  22. 22. Not  really..
  23. 23.  but  you  can  make  APIs  magical  
  24. 24. ask  questions  
  25. 25. is  your  API  RESTful?  
  26. 26. .  stateless  .  cacheable  .  HTTP  methods    
  27. 27. take  action  depending  on  the  type  of  HTTP  request  
  28. 28. GET        -­‐  retrieve  POST      -­‐  create  PUT      -­‐  update  DELETE    -­‐  destroy    
  29. 29. using  these  verbs  API  clients  act  on  resources  
  30. 30. your  API  is  only  as  good  as  the  resources  it  delivers  
  31. 31. are  your  resources  well  defined?  
  32. 32. say  you  have  a  django  project  
  33. 33. it  has  a  lot  of  models  
  34. 34. attractive  models  
  35. 35. resource  !=  model  
  36. 36. resource  =  unit  of  information  
  37. 37. that  you  own  and  everyone  else  wants  a  piece  
  38. 38. define  them  with  care  
  39. 39. class  Book  (Model):    title    =  Charfield(...)    summary  =  Charfield(...)    isbn10    =  Charfield(...)    isbn13    =  Charfield(...)      authors    =  ManyToManyField(...)    created    =  DateTimeField(...)    
  40. 40. {    ‘title’    :  ‘...’,    ‘summary’  :  ‘...’,    ‘authors’  :  [‘...’,  ‘...’],    ‘editions’  :  [{      ‘number’          :  ‘...’,      ‘publisher’        :  ‘...’,      ‘date_published’:  ‘...’,      }],    ‘is_favorite’ :  true,    }  
  41. 41. class  Book  (Model):    title    =  Charfield(...)    summary  =  Charfield(...)    isbn10    =  Charfield(...)    isbn13    =  Charfield(...)      authors    =  ManyToManyField(...)    created    =  DateTimeField(...)    {    ‘title’    :  ‘...’,    ‘summary’  :  ‘...’,    ‘authors’  :  [‘...’,  ‘...’],    ‘editions’  :  [{      ‘number’          :  ‘...’,      ‘publisher’        :  ‘...’,      ‘date_published’:  ‘...’,      }],    ‘is_favorite’  :  true,  }  
  42. 42. resource  !=  model  
  43. 43. concise  &  complete    
  44. 44. but  are  resources  the  only  thing  you  send  in  API  responses?  
  45. 45. resource  structures  vary  wildly  
  46. 46. API  responses  should  be  predictable  
  47. 47. API  responses  should  be  parsable  
  48. 48. API  responses  should  be  uniform  
  49. 49. API RESPONSEwrap  them  in  envelopes  
  50. 50. add  metadata  about  response  
  51. 51. .  HTTP  status  code  .  error  code  &  message  .  pagination  data  
  52. 52. {    ‘status’  :  200,    ‘errors’  :  [],    ‘data’  :  {      ‘title’  :  ‘...’,      ‘isbn10’  :  ‘...’,      ‘summary’  :  ‘...’,        ‘authors’  :  [‘...’,  ‘...’],      }    }  
  53. 53. {    ‘status’  :  400,    ‘errors’  :  [{      ‘code’    :  5,        ‘message’    :  ‘OMG  form  errors!’,      ‘data’    :  {          ‘title’:  [‘Field  required’],          }        }],    ‘data’:  {},      }  
  54. 54. {    ‘status’  :  200,    ‘errors’  :  [],    ‘data’  :  {      ‘pagination’:  {        ‘count’  :  134,          ‘pages’  :  7,          }        ‘results’:  [...],      }    }  
  55. 55. now  that  you  have  uniform  responses  
  56. 56. ask  yourself  
  57. 57. would  you  support  different  serialization  formats?  
  58. 58. the  world  is  moving  towards  json  
  59. 59. it’s  a  greener  alternative  to  XML  
  60. 60. but  you  might  want  to  support  jsonp  
  61. 61. or  XML  
  62. 62. more  formats  =  more  testing  
  63. 63. more  formats  =  more  support   requests  
  64. 64. it’s  cool  if  you  can  accommodate  
  65. 65. serialization  parameters  !=  cool  format=xml  
  66. 66. client  can  add  .json  or  .xml  at  end  of  URL  
  67. 67. Now  you   see  it.. http://api.domain.com/v1.0/books/game-­‐of-­‐thrones.xml  
  68. 68. Now  you   don’t.. http://api.domain.com/v1.0/books/game-­‐of-­‐thrones  
  69. 69. in  absence  of  specified  format  return  default  
  70. 70. then  it’s  all  good  
  71. 71. Did  you   notice  that? http://api.domain.com/v1.0/books/game-­‐of-­‐thrones  
  72. 72. versioning  your  API  is  cool  
  73. 73. 6  days  of  beer  in  Portland  
  74. 74. your  pants  might  not  fit  
  75. 75. 6  months  of  deployment  in  production  
  76. 76. your  APIs  might  not  fit  
  77. 77. version  your  API  
  78. 78. Why  hello   there! http://api.domain.com/v1.0/books/game-­‐of-­‐thrones  
  79. 79. save  URL  namespace  
  80. 80. now  to  one  of  the  most  important  questions..  
  81. 81. Is  the  anomaly   systemic,  creating  fluctuations  in  even  the  most  simplistic   equations?
  82. 82. always  hated  that  guy  
  83. 83. the  question  we  are  looking  for  is..  
  84. 84. Is  your  API  secure?
  85. 85. some  endpoints  need  to  be  secure  
  86. 86. private  user  data  
  87. 87. resources  that  bring  revenue  
  88. 88. to  protect  resources,  use  an  authentication  scheme  
  89. 89. use  Oauth  
  90. 90. use  Oauth  1.0  
  91. 91. use  Oauth  2.0  
  92. 92. use  2-­‐legged  Oauth  for  applications  directly  accessing  resources  
  93. 93. use  3-­‐legged  Oauth  for  applications  accessing  resources  on  behalf  of  users  
  94. 94. use  HTTPS  for  calls  to  protected  resources  
  95. 95. using  Oauth  might  get  a  little  complex  
  96. 96. how  to  minimize  that  complexity?  
  97. 97. what’s  the  easiest  route  to  securing  your  API?  
  98. 98. and  making  your  API  comply  with  the  concepts  we  discussed?  
  99. 99. bring  us  to  the  next  question..  
  100. 100. do  you  use  any  API  frameworks?  
  101. 101. django-­‐piston  
  102. 102. tastypie  
  103. 103. django-­‐rest-­‐framework  
  104. 104. dj-­‐webmachine  
  105. 105. take  your  pick  
  106. 106. none  of  these  frameworks  will  do  everything  for  you  
  107. 107. make  them  work  for  you  
  108. 108. to  build  
  109. 109. we  used  django-­‐piston  
  110. 110. piston  has  built  in  Oauth  support  
  111. 111. and  a  flexible  architecture  using  pluggable  components  
  112. 112. pluggable  resource  handlers  
  113. 113. pluggable  emitters  (serializers)  
  114. 114. pluggable  authentication  
  115. 115. we  enhanced  django-­‐piston  
  116. 116. .  pluggable  envelopes  .  form  error  feedbacks  .  anonymous  tokens  
  117. 117. added   resource  definition   subsystem  
  118. 118. class  BookDetailedView  (PistonView):          fields  =  [    ‘title’,    ‘isbn10’,    ‘pages’,    Field(      ‘’,      lambda  x:  [y.name  for  y  in  x.authors.all()],      destination=‘authors’,      ),    ]    
  119. 119. return  BookDetailedView(book)  
  120. 120. {    ‘title’  :  ‘...’,    ‘isbn10’  :  ‘...’,    ‘pages’  :  357,      ‘authors’  :  [‘...’,  ‘...’],  }  
  121. 121. http://github.com/pbs-­‐education/django-­‐piston  
  122. 122. again,  you  have  quite  a  few  choices  
  123. 123. .  django-­‐piston  .  tastypie  .  django-­‐rest-­‐framework  .  dj-­‐webmachine  
  124. 124. take  your  pick  
  125. 125. make  them  work  for  you  
  126. 126. build  your  API  right  
  127. 127. join  the  party  
  128. 128. thank  you  
  129. 129. tarequeh    -­‐  slideshare.net    -­‐  twitter    -­‐  .com  

×