api design & security in django
DESCRIPTION
Here I discuss web service API best practices for django based projectsTRANSCRIPT
API Design & Security in Django
Tareque Hossain Education Technology
1
2
Fundamentals of API
• Architecture
• Defining resources
• Uniform response
• Serialization
• Versioning
• Authentication
3
Your API should be RESTful
• Stateless
• Client-server
• Cacheable
• Uniform Interface o HTTP GET/POST/PUT/DELETE
4
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
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
Resource: Example
7
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
Uniform Response
9
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
Uniformity: Example
http://api.pbslearningmedia.org/v1.0/likes/content/lsps07.sci.phys.matter
11
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
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
Serialization
• JSON rocks
• RESTful API isn’t about restrictions
• API should support: o JSONP
o JSON
o YAML
o XML
14
Serialization..
• Have a default, say: JSON
• But if client requests different format, then deliver accordingly (if supported)
http://api.pbslearningmedia.org/v1.0/content/contents/cdda1ed2-da03
http://api.pbslearningmedia.org/v1.0/content/contents/cdda1ed2-da03.xml
15
Serialization..
• Have a default, say: JSON
• But if client requests different format, then deliver accordingly (if supported)
http://api.pbslearningmedia.org/v1.0/content/contents/cdda1ed2-da03
http://api.pbslearningmedia.org/v1.0/content/contents/cdda1ed2-da03.xml
16
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
o New
http://api.pbslearningmedia.org/v1.0/content/contents/cdda1ed2-da03
http://api.pbslearningmedia.org/v2.0/content/contents/cdda1ed2-da03
17
Versioning • Write separate URL definitions & handlers
for different versions
18
Authentication
19
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
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
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
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
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
Oauth: Overview
25
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
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
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
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
31
urls.py
32
GET Response
33
POST Error Response
34
35
Q/A?
• Slides are available at: o www.codexn.com
• Presenting a talk on API at djangocon 2011
36
utils.py
37
auth.py
38