API Design & Security in django

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.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



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