Here I discuss web service API best practices for django based projects

1. API Design & Security in
Django
Tareque Hossain
Education Technology
1

2. 2

3. Fundamentals of API
• Architecture
• Defining resources
• Uniform response
• Serialization
• Versioning
• Authentication
3

4. Your API should be RESTful
• Stateless
• Client-server
• Cacheable
• Uniform Interface
o HTTP GET/POST/PUT/DELETE
4

5. Defining Resources
• Resource
o Cohesive set of information
o Of interest to client
• Identified by URL
o Uniform Resource Locator
http://api.flickr.com/services/rest/?method=flickr.photos.getSizes&photo_id=5983860647
5

6. Defining Resources..
• Resource != Django Model
o May consist of data from several different
model instances
• Attributes
• Values returned from member functions
o May contain data completely unrelated to
any model instance
• Date & time of response
6

7. Resource: Example
7

8. Defining Resources...
• Notice how:
o Each instance of book has (similar to
select_related):
• Authors
• Editions
• Awards
o is_favorite indicates whether the client
user has marked this book as favorite
8

9. Uniform Response
9

10. Uniform Response
• Resource attributes vary wildly
• Provide uniform response:
o Include resource independent attributes
• HTTP Status code
• Error code (you define for your API)
• Error message or data
10

11. Uniformity: Example
http://api.pbslearningmedia.org/v1.0/likes/content/lsps07.sci.phys.matter
11

12. Uniform Response
• Include meta information:
o Facets for certain attributes
• Choices for form fields
o Pagination (if applicable)
• Result count
• Page number
• Resource per page
12

13. Uniform Response
• Present in all responses (GET/POST/
PUT)
• Not in response for DELETE
• HTTP 1.1 forbids message body for
1.xx, 204 (DELETE) & 304
• Can be parsed by client even if it can’t
parse the actual resource data
13

14. Serialization
• JSON rocks
• RESTful API isn’t about restrictions
• API should support:
o JSONP
o JSON
o YAML
o XML
14

15. Serialization..
• Have a default, say: JSON
http://api.pbslearningmedia.org/v1.0/content/contents/cdda1ed2-da03
• But if client requests different format,
then deliver accordingly (if supported)
http://api.pbslearningmedia.org/v1.0/content/contents/cdda1ed2-da03.xml
15

16. Serialization..
• Have a default, say: JSON
http://api.pbslearningmedia.org/v1.0/content/contents/cdda1ed2-da03
• But if client requests different format,
then deliver accordingly (if supported)
http://api.pbslearningmedia.org/v1.0/content/contents/cdda1ed2-da03.xml
16

17. Versioning
• APIs change all the time
o Don’t break your existing API
o Roll out new API set while old ones are
functioning (if data models don’t change)
• Save namespace
o Old
http://api.pbslearningmedia.org/v1.0/content/contents/cdda1ed2-da03
o New
http://api.pbslearningmedia.org/v2.0/content/contents/cdda1ed2-da03
17

18. Versioning
• Write separate URL definitions & handlers
for different versions
18

19. Authentication
19

20. Authentication
• Not all APIs endpoints are public
• Use authentication to protect your API
o Oauth is great
http://wiki.oauth.net/w/page/12238551/ServiceProviders
20

21. Oauth: Overview
• Two types of access:
o Resource accessed by web applications
directly
• User independent
• Accessing Twitter’s aggregated public
timeline
o Resource accessed by web applications on
behalf of users
• Accessing user’s private timeline
21

22. Oauth: Overview
• Credentials consist of:
o Consumer key & secret (application)
o Access token & token secret (user)
• Each request contains:
o oauth_consumer_key
o oauth_token
o oauth_signature_method
o oauth_signature
o oauth_timestamp
o oauth_nonce
o oauth_version
22

23. Oauth: 2-legged
• Resource accessed by web
applications directly
o Use 2-legged Oauth
o Leave oauth_token empty
http://oauth.googlecode.com/svn/spec/ext/consumer_request/1.0/drafts/2/spec.html
23

24. Oauth: 3-legged
• Resource accessed by web
applications on behalf of users
o Use 3-legged Oauth
o User explicitly authorizes 3rd party
applications to access protected resources
• Allow apps to fetch your tweet stream
http://www.flickr.com/services/api/auth.oauth.html
24

25. Oauth: Overview
25

26. Whoa..
• Oauth can be overwhelming
• But it’s great once you get to know it
• API frameworks like django-piston
supports Oauth out of the box
26

27. API Frameworks?
• API frameworks make it easier for you to
build APIs in django
• Tastypie
o http://django-tastypie.readthedocs.org/en/latest/
• django-piston
o https://bitbucket.org/jespern/django-piston/wiki/Home
• django-rest-framework
o http://django-rest-framework.org/
• dj-webmachine
o http://benoitc.github.com/dj-webmachine/
27

28. django-piston
• At PBS Education, we chose django-
piston
o Primarily because of its built in Oauth support
• Original release is not actively
maintained
• We have modified django-piston
o To adapt the concepts I have discussed today
http://github.com/pbs-education/django-piston
28

29. Lets write some API
• Writing API using django-piston is easy
• Instead of writing views for your URLs,
write handlers
• Extend piston’s BaseHandler class
o Override following methods:
• read for GET
• create for POST
• update for PUT
• delete for DELETE
29

30. 30

31. 31

32. urls.py
32

33. GET Response
33

34. POST Error Response
34

35. 35

36. Q/A?
• Slides are available at:
o www.codexn.com
• Presenting a talk on API at djangocon
2011
36

37. utils.py
37

38. auth.py
38