This document discusses API design and security in Django. It covers fundamentals of API including defining resources, uniform responses, serialization, and versioning. Authentication with OAuth is also explained. Django frameworks like django-piston are recommended for building APIs as they support features like OAuth out of the box. Writing API handlers with django-piston is demonstrated to be easy by extending its BaseHandler class and overriding methods for different HTTP methods.

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