Your SlideShare is downloading. ×
  • Like
RESTful APIs: Promises & lies
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Now you can save presentations on your phone or tablet

Available for both IPhone and Android

Text the download link to your phone

Standard text messaging rates apply

RESTful APIs: Promises & lies

  • 4,958 views
Published

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

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
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
  • Valentin, I beg to disagree. Could you elaborate?
    Are you sure you want to
    Your message goes here
  • Envelopes? Extensions for content-types?

    This is so NOT REST.
    Are you sure you want to
    Your message goes here
  • Image Credits Pony: http://www.flickr.com/photos/avalonstar/2842638666/sizes/m/in/photostream/ JSON Logo: http://droidweb.com/2011/04/dealing-with-json-in-android/ Not really: http://www.flickr.com/photos/neilwinch/5942466100/sizes/z/in/photostream/ Kitkat: http://en.wikipedia.org/wiki/File:KitKat_chunky.jpg Guns/Flowers: http://jacko41.deviantart.com/art/Guns-Flowers-Tribes-and-Face-176108822
    Are you sure you want to
    Your message goes here
No Downloads

Views

Total Views
4,958
On SlideShare
0
From Embeds
0
Number of Embeds
4

Actions

Shares
Downloads
92
Comments
3
Likes
13

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    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!

Transcript

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