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