RESTful APIs: Promises & lies

6,075 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
4 Comments
15 Likes
Statistics
Notes
No Downloads
Views
Total views
6,075
On SlideShare
0
From Embeds
0
Number of Embeds
558
Actions
Shares
0
Downloads
103
Comments
4
Likes
15
Embeds 0
No embeds

No notes for slide
  • ----- Meeting Notes (9/7/11 09:17) -----Let's take a look at these company logos. You are familiar with most of them
  • Take a look again!
  • Because
  • So what’s the deal with promises & lies?
  • So how do start building APIs? Do you make a django project and spit some json out?
  • And you get magical API
  • Unfortunately, that’s not true
  • You just have to ask yourself a few questions..
  • RESTful APIs are stateless, cacheable and relies on HTTP methods
  • In RESTful APIs, handlers..
  • Speaking of resources
  • Resources are units of information that are of interest to your clients..
  • Units of information
  • Just like Kitkat
  • Now let’s take a look at the resource that can be built around that.. Besides some model attributes, it includes editions. Editions have further attributes that are of interest to API consumers. Lastly, there can be attributes that are very specific to the consumer requesting the resource.
  • Now let’s put them next to each other for a better understanding
  • Remember this guy
  • He always brought friends
  • Many friends
  • How was Neo able to fight them off, all by himself?
  • Because they were all agents Smiths. Their tactics were uniform. So Neo knew exactly how to approach them.
  • So wrap them in envelopes
  • Include information like.. when appropriate
  • For example you can deliver a response that has HTTP status code, errors and finally the data for a successful GET request
  • If a POST or PUT request fails, you can add the error metadata to your response.Makes it easy for the client to understand what exactly went wrong
  • Let’s take a look at a response that provides pagination information. You can include fields like how many results were found, how many pages that maps to etc.
  • You should remember..
  • It’s perfectly alright to have multiple serialization formats if you can accommodate the extra efforts
  • But don’t accept serialization formats as GET parameters
  • Like that
  • Or they can choose not to
  • Like that
  • Starting with Oauth 2.0 it’s mandated that you use HTTPS for calls to protected resources..
  • How do you minimize that complexity
  • Next, API frameworks
  • Next, API frameworks
  • A major feature we added was..
  • Lets take a look at that now.. this is how you’d define the resource for the Book model we previously discussed. It takes an object and uses your definitions to create a resource
  • Once you have that definition, you callit like this..
  • For example you can deliver a response that has HTTP status code, errors and finally the data for a successful GET request
  • You can find all necessary information about this enhanced django piston on PBS Education’s Github profile
  • We did!
  • 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  

    ×