Django Rest Framework

Django Rest Framework
Documentation
Release 2.3
Tom Christie
December 06, 2014
Contents
Requirements
Installation
Example
Quickstart
Tutorial
5.1 Quickstart
5.2 Tutorial 1:
5.3 Tutorial 2:
5.4 Tutorial 3:
5.5 Tutorial 4:
5.6 Tutorial 5:
5.7 Tutorial 6:
. . . . . . . . . . . . . . . . . . .
Serialization . . . . . . . . . . . .
Requests and Responses . . . . . .
Class Based Views . . . . . . . . .
Authentication & Permissions . . .
Relationships & Hyperlinked APIs
ViewSets & Routers . . . . . . . .
API Guide
Topics
7.1 Documenting your API . . . . . . . .
7.2 Working with AJAX, CSRF & CORS
7.3 Browser enhancements . . . . . . . .
7.4 The Browsable API . . . . . . . . .
7.5 REST, Hypermedia & HATEOAS . .
7.6 Contributing to REST framework . .
7.7 Issues . . . . . . . . . . . . . . . . .
7.8 Development . . . . . . . . . . . . .
7.9 Documentation . . . . . . . . . . . .
7.10 Third party packages . . . . . . . . .
7.11 Django REST framework 2 . . . . .
7.12 REST framework 2.2 announcement .
7.13 REST framework 2.3 announcement .
7.14 API Changes . . . . . . . . . . . . .
7.15 Other notes . . . . . . . . . . . . . .
7.16 Release Notes . . . . . . . . . . . .
7.17 Credits . . . . . . . . . . . . . . . .
Indices and tables
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11
11
14
22
25
28
32
35
39
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
41
41
45
46
48
52
54
54
55
56
58
58
60
65
67
70
71
85
93
Development
95
10 Support
97
11 Security
99
12 License
101
ii
Django Rest Framework Documentation, Release 2.3
Attention: This a non-official Sphinx version of the Django REST Frameworks documentation, mantained by
Martn Gaitn
As the official documentation is written using Markdown and custom scripts, it cant be rendered using Sphinx nor
take advantage of Read the Docss downloads in many formats.
Django REST framework is a powerful and flexible toolkit that makes it easy to build Web APIs.
Some reasons you might want to use REST framework:
The Web browseable API is a huge usability win for your developers.
Authentication policies including OAuth1a and OAuth 2 out of the box.
Serialization that supports both ORM and non-ORM data sources.
Customizable all the way down - just use regular function-based views if you dont need the more powerful
features
Extensive documentation and great community support.
Used and trusted by large companies such as Mozilla and Eventbrite.
Contents
Figure 1: Screenshot from the browsable API
Contents
CHAPTER 1
Requirements
REST framework requires the following:

Python (2.6.5+, 2.7, 3.2, 3.3)
Django (1.3, 1.4, 1.5, 1.6)
The following packages are optional:
Markdown <http://pypi.python.org/pypi/Markdown/>_ (2.1.0+) Markdown support for the browsable API.
PyYAML <http://pypi.python.org/pypi/PyYAML>_ (3.10+) YAML content-type support.
defusedxml <https://pypi.python.org/pypi/defusedxml>_ (0.3+) XML content-type support.
django-filter <http://pypi.python.org/pypi/django-filter>_ (0.5.4+) Filtering support.
django-oauth-plus <https://bitbucket.org/david/django-oauth-plus/wiki/Home>_ (2.0+) and oauth2 (1.5.211+)
OAuth 1.0a support.
django-oauth2-provider <https://github.com/caffeinehit/django-oauth2-provider>_ (0.2.3+) OAuth 2.0 support.
django-guardian <https://github.com/lukaszb/django-guardian> (1.1.1+) Object level permissions support.
Note: The oauth2 Python package is badly misnamed, and actually provides OAuth 1.0a support. Also note that
packages required for both OAuth 1.0a, and OAuth 2.0 are not yet Python 3 compatible.
Chapter 1. Requirements
CHAPTER 2
Installation
Install using pip, including any optional packages you want...

pip install djangorestframework
pip install markdown
# Markdown support for the browsable API.
pip install django-filter # Filtering support
...or clone the project from github.

git clone git@github.com:tomchristie/django-rest-framework.git
Add rest_framework to your INSTALLED_APPS setting.

INSTALLED_APPS = (
...
rest_framework,
)
If youre intending to use the browsable API youll probably also want to add REST frameworks login and logout
views. Add the following to your root urls.py file.
urlpatterns = patterns(,
...
url(râpi-auth/, include(rest_framework.urls, namespace=rest_framework))
)
Note that the URL path can be whatever you want, but you must include rest_framework.urls with the
rest_framework namespace.
Chapter 2. Installation
CHAPTER 3
Example
Lets take a look at a quick example of using REST framework to build a simple model-backed API.
Well create a read-write API for accessing users and groups.
Any global settings for a REST framework API are kept in a single configuration dictionary named
REST_FRAMEWORK. Start off by adding the following to your settings.py module:
REST_FRAMEWORK = {
# Use hyperlinked styles by default.
# Only used if the serializer_class attribute is not set on a view.
DEFAULT_MODEL_SERIALIZER_CLASS:
rest_framework.serializers.HyperlinkedModelSerializer,
# Use Djangos standard django.contrib.auth permissions,
# or allow read-only access for unauthenticated users.
DEFAULT_PERMISSION_CLASSES: [
rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly
]
}
Dont forget to make sure youve also added rest_framework to your INSTALLED_APPS.
Were ready to create our API now. Heres our projects root urls.py module:
from django.conf.urls import url, patterns, include
from django.contrib.auth.models import User, Group
from rest_framework import viewsets, routers
# ViewSets define the view behavior.
class UserViewSet(viewsets.ModelViewSet):
model = User
class GroupViewSet(viewsets.ModelViewSet):
model = Group
# Routers provide an easy way of automatically determining the URL conf.

router = routers.DefaultRouter()
router.register(rusers, UserViewSet)
router.register(rgroups, GroupViewSet)
# Wire up our API using automatic URL routing.

# Additionally, we include login URLs for the browseable API.
url(r^, include(router.urls)),
)
Chapter 3. Example
CHAPTER 4
Quickstart
Cant wait to get started? The quickstart guide is the fastest way to get up and running, and building APIs with REST
framework.
10
Chapter 4. Quickstart
CHAPTER 5
Tutorial
The tutorial will walk you through the building blocks that make up REST framework. Itll take a little while to get
through, but itll give you a comprehensive understanding of how everything fits together, and is highly recommended
reading.
5.1 Quickstart
Were going to create a simple API to allow admin users to view and edit the users and groups in the system.
5.1.1 Project setup

Create a new Django project named tutorial, then start a new app called quickstart.
# Set up a new project
django-admin.py startproject tutorial
cd tutorial
# Create a virtualenv to isolate our package dependencies locally
virtualenv env
source env/bin/activate # On Windows use env\Scripts\activate
# Install Django and Django REST framework into the virtualenv
pip install django
# Create a new app
python manage.py startapp quickstart
Next youll need to get a database set up and synced. If you just want to use SQLite for now, then youll want to edit
your tutorial/settings.py module to include something like this:
DATABASES = {
default: {
ENGINE: django.db.backends.sqlite3,
NAME: database.sql,
USER: ,
PASSWORD: ,
HOST: ,
PORT:
}
}
11
The run syncdb like so:

python manage.py syncdb
Once youve set up a database and got everything synced and ready to go, open up the apps directory and well get
coding...
5.1.2 Serializers
First up were going to define some serializers in quickstart/serializers.py that well use for our data
representations.
from rest_framework import serializers
class UserSerializer(serializers.HyperlinkedModelSerializer):
class Meta:
model = User
fields = (url, username, email, groups)
class GroupSerializer(serializers.HyperlinkedModelSerializer):
class Meta:
model = Group
fields = (url, name)
Notice that were using hyperlinked relations in this case, with HyperlinkedModelSerializer. You can also
use primary key and various other relationships, but hyperlinking is good RESTful design.
5.1.3 Views
Right, wed better write some views then. Open quickstart/views.py and get typing.
from rest_framework import viewsets
from quickstart.serializers import UserSerializer, GroupSerializer
"""
API endpoint that allows users to be viewed or edited.
"""
queryset = User.objects.all()
serializer_class = UserSerializer
"""
API endpoint that allows groups to be viewed or edited.
"""
queryset = Group.objects.all()
serializer_class = GroupSerializer
Rather than write multiple views were grouping together all the common behavior into classes called ViewSets.
12
Chapter 5. Tutorial
We can easily break these down into individual views if we need to, but using viewsets keeps the view logic nicely
organized as well as being very concise.
Notice that our viewset classes here are a little different from those in the frontpage example, as they include
queryset and serializer_class attributes, instead of a model attribute.
For trivial cases you can simply set a model attribute on the ViewSet class and the serializer and queryset will be
automatically generated for you. Setting the queryset and/or serializer_class attributes gives you more
explicit control of the API behaviour, and is the recommended style for most applications.
5.1.4 URLs
Okay, now lets wire up the API URLs. On to tutorial/urls.py...
from django.conf.urls import patterns, url, include
from rest_framework import routers
from quickstart import views
router.register(rusers, views.UserViewSet)
router.register(rgroups, views.GroupViewSet)
)
Because were using viewsets instead of views, we can automatically generate the URL conf for our API, by simply
registering the viewsets with a router class.
Again, if we need more control over the API URLs we can simply drop down to using regular class based views, and
writing the URL conf explicitly.
Finally, were including default login and logout views for use with the browsable API. Thats optional, but useful if
your API requires authentication and you want to use the browsable API.
5.1.5 Settings
Wed also like to set a few global settings. Wed like to turn on pagination, and we want our API to only be accessible
to admin users. The settings module will be in tutorial/settings.py
INSTALLED_APPS = (
...
rest_framework,
)
REST_FRAMEWORK = {
DEFAULT_PERMISSION_CLASSES: (rest_framework.permissions.IsAdminUser,),
PAGINATE_BY: 10
}
Okay, were done.
5.1. Quickstart
13
5.1.6 Testing our API

Were now ready to test the API weve built. Lets fire up the server from the command line.
python ./manage.py runserver
We can now access our API, both from the command-line, using tools like curl...
bash: curl -H Accept: application/json; indent=4 -u admin:password http://127.0.0.1:8000/users/
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"email": "admin@example.com",
"groups": [],
"url": "http://127.0.0.1:8000/users/1/",
"username": "admin"
},
{
"email": "tom@example.com",
"groups": [
],
"url": "http://127.0.0.1:8000/users/2/",
"username": "tom"
}
]
}
Or directly through the browser...

Great, that was easy!
If you want to get a more in depth understanding of how REST framework fits together head on over to the tutorial, or
start browsing the API guide.
5.2 Tutorial 1: Serialization

5.2.1 Introduction
This tutorial will cover creating a simple pastebin code highlighting Web API. Along the way it will introduce the
various components that make up REST framework, and give you a comprehensive understanding of how everything
fits together.
The tutorial is fairly in-depth, so you should probably get a cookie and a cup of your favorite brew before getting
started. If you just want a quick overview, you should head over to the quickstart documentation instead.
Note: The code for this tutorial is available in the tomchristie/rest-framework-tutorial repository on GitHub. The
completed implementation is also online as a sandbox version for testing, available here.
14
Chapter 5. Tutorial
Figure 5.1: Quick start image
5.2. Tutorial 1: Serialization
15
5.2.2 Setting up a new environment

Before we do anything else well create a new virtual environment, using virtualenv. This will make sure our package
configuration is kept nicely isolated from any other projects were working on.
:::bash
virtualenv env
source env/bin/activate
Now that were inside a virtualenv environment, we can install our package requirements.
pip install django
pip install pygments # Well be using this for the code highlighting
Note: To exit the virtualenv environment at any time, just type deactivate. For more information see the virtualenv
documentation.
5.2.3 Getting started

Okay, were ready to get coding. To get started, lets create a new project to work with.
cd ~
django-admin.py startproject tutorial
cd tutorial
Once thats done we can create an app that well use to create a simple Web API.
python manage.py startapp snippets
The simplest way to get up and running will probably be to use an sqlite3 database for the tutorial. Edit
the tutorial/settings.py file, and set the default database "ENGINE" to "sqlite3", and "NAME" to
"tmp.db".
DATABASES = {
default: {
ENGINE: django.db.backends.sqlite3,
NAME: tmp.db,
USER: ,
PASSWORD: ,
HOST: ,
PORT: ,
}
}
Well also need to add our new snippets app and the rest_framework app to INSTALLED_APPS.
INSTALLED_APPS = (
...
rest_framework,
snippets,
)
We also need to wire up the root urlconf, in the tutorial/urls.py file, to include our snippet apps URLs.
url(r^, include(snippets.urls)),
)
Okay, were ready to roll.

16
Chapter 5. Tutorial
5.2.4 Creating a model to work with

For the purposes of this tutorial were going to start by creating a simple Snippet model that is used to store code
snippets. Go ahead and edit the snippets apps models.py file. Note: Good programming practices include
comments. Although you will find them in our repository version of this tutorial code, we have omitted them here to
focus on the code itself.
from django.db import models
from pygments.lexers import get_all_lexers
from pygments.styles import get_all_styles
LEXERS = [item for item in get_all_lexers() if item[1]]
LANGUAGE_CHOICES = sorted([(item[1][0], item[0]) for item in LEXERS])
STYLE_CHOICES = sorted((item, item) for item in get_all_styles())
class Snippet(models.Model):
created = models.DateTimeField(auto_now_add=True)
title = models.CharField(max_length=100, blank=True, default=)
code = models.TextField()
linenos = models.BooleanField(default=False)
language = models.CharField(choices=LANGUAGE_CHOICES,
default=python,
max_length=100)
style = models.CharField(choices=STYLE_CHOICES,
default=friendly,
max_length=100)
class Meta:
ordering = (created,)
Dont forget to sync the database for the first time.

python manage.py syncdb
5.2.5 Creating a Serializer class

The first thing we need to get started on our Web API is provide a way of serializing and deserializing the snippet
instances into representations such as json. We can do this by declaring serializers that work very similar to Djangos
forms. Create a file in the snippets directory named serializers.py and add the following.
from django.forms import widgets
from rest_framework import serializers
from snippets.models import Snippet, LANGUAGE_CHOICES, STYLE_CHOICES
class SnippetSerializer(serializers.Serializer):
pk = serializers.Field() # Note: Field is an untyped read-only field.
title = serializers.CharField(required=False,
max_length=100)
code = serializers.CharField(widget=widgets.Textarea,
max_length=100000)
linenos = serializers.BooleanField(required=False)
language = serializers.ChoiceField(choices=LANGUAGE_CHOICES,
default=python)
style = serializers.ChoiceField(choices=STYLE_CHOICES,
default=friendly)
17
def restore_object(self, attrs, instance=None):

"""
Create or update a new snippet instance, given a dictionary
of deserialized field values.
Note that if we dont define this method, then deserializing
data will simply return a dictionary of items.
"""
if instance:
# Update existing instance
instance.title = attrs.get(title, instance.title)
instance.code = attrs.get(code, instance.code)
instance.linenos = attrs.get(linenos, instance.linenos)
instance.language = attrs.get(language, instance.language)
instance.style = attrs.get(style, instance.style)
return instance
# Create new instance
return Snippet(**attrs)
The first part of serializer class defines the fields that get serialized/deserialized. The restore_object method
defines how fully fledged instances get created when deserializing data.
Notice that we can also use various attributes that would typically be used on form fields, such as
widget=widgets.Textarea. These can be used to control how the serializer should render when displayed
as an HTML form. This is particularly useful for controlling how the browsable API should be displayed, as well see
later in the tutorial.
We can actually also save ourselves some time by using the ModelSerializer class, as well see later, but for now
well keep our serializer definition explicit.
5.2.6 Working with Serializers

Before we go any further well familiarize ourselves with using our new Serializer class. Lets drop into the Django
shell.
python manage.py shell
Okay, once weve got a few imports out of the way, lets create a couple of code snippets to work with.
from
from
from
from
snippets.models import Snippet

snippets.serializers import SnippetSerializer
rest_framework.renderers import JSONRenderer
rest_framework.parsers import JSONParser
snippet = Snippet(code=foo = "bar"\n)

snippet.save()
snippet = Snippet(code=print "hello, world"\n)
snippet.save()
Weve now got a few snippet instances to play with. Lets take a look at serializing one of those instances.
serializer = SnippetSerializer(snippet)
serializer.data
# {pk: 2, title: u, code: uprint "hello, world"\n, linenos: False, language: upython,
18
Chapter 5. Tutorial
At this point weve translated the model instance into Python native datatypes. To finalize the serialization process we
render the data into json.
content = JSONRenderer().render(serializer.data)
content
# {"pk": 2, "title": "", "code": "print \\"hello, world\\"\\n", "linenos": false, "language": "pytho
Deserialization is similar. First we parse a stream into Python native datatypes...

# This import will use either StringIO.StringIO or io.BytesIO
# as appropriate, depending on if were running Python 2 or Python 3.
from rest_framework.compat import BytesIO
stream = BytesIO(content)
data = JSONParser().parse(stream)
...then we restore those native datatypes into to a fully populated object instance.
serializer = SnippetSerializer(data=data)
serializer.is_valid()
# True
serializer.object
# <Snippet: Snippet object>
Notice how similar the API is to working with forms. The similarity should become even more apparent when we start
writing views that use our serializer.
We can also serialize querysets instead of model instances. To do so we simply add a many=True flag to the serializer
arguments.
serializer = SnippetSerializer(Snippet.objects.all(), many=True)

serializer.data
# [{pk: 1, title: u, code: ufoo = "bar"\n, linenos: False, language: upython, style
5.2.7 Using ModelSerializers

Our SnippetSerializer class is replicating a lot of information thats also contained in the Snippet model. It
would be nice if we could keep our code a bit more concise.
In the same way that Django provides both Form classes and ModelForm classes, REST framework includes both
Serializer classes, and ModelSerializer classes.
Lets look at refactoring our serializer using the ModelSerializer
snippets/serializers.py again, and edit the SnippetSerializer class.
class.
Open
the
file
class SnippetSerializer(serializers.ModelSerializer):
class Meta:
model = Snippet
fields = (id, title, code, linenos, language, style)
5.2.8 Writing regular Django views using our Serializer

Lets see how we can write some API views using our new Serializer class. For the moment we wont use any of
REST frameworks other features, well just write the views as regular Django views.
Well start off by creating a subclass of HttpResponse that we can use to render any data we return into json.
Edit the snippets/views.py file, and add the following.
19
from
from
from
from
from
from
django.http import HttpResponse

django.views.decorators.csrf import csrf_exempt
rest_framework.renderers import JSONRenderer
rest_framework.parsers import JSONParser
class JSONResponse(HttpResponse):
"""
An HttpResponse that renders its content into JSON.
"""
def __init__(self, data, **kwargs):
content = JSONRenderer().render(data)
kwargs[content_type] = application/json
super(JSONResponse, self).__init__(content, **kwargs)
The root of our API is going to be a view that supports listing all the existing snippets, or creating a new snippet.
@csrf_exempt
def snippet_list(request):
"""
List all code snippets, or create a new snippet.
"""
if request.method == GET:
snippets = Snippet.objects.all()
serializer = SnippetSerializer(snippets, many=True)
return JSONResponse(serializer.data)
elif request.method == POST:
data = JSONParser().parse(request)
serializer = SnippetSerializer(data=data)
if serializer.is_valid():
serializer.save()
return JSONResponse(serializer.data, status=201)
return JSONResponse(serializer.errors, status=400)
Note that because we want to be able to POST to this view from clients that wont have a CSRF token we need to
mark the view as csrf_exempt. This isnt something that youd normally want to do, and REST framework views
actually use more sensible behavior than this, but itll do for our purposes right now.
Well also need a view which corresponds to an individual snippet, and can be used to retrieve, update or delete the
snippet.
@csrf_exempt
def snippet_detail(request, pk):
"""
Retrieve, update or delete a code snippet.
"""
try:
snippet = Snippet.objects.get(pk=pk)
except Snippet.DoesNotExist:
return HttpResponse(status=404)
elif request.method == PUT:
data = JSONParser().parse(request)
20
Chapter 5. Tutorial
serializer = SnippetSerializer(snippet, data=data)

serializer.save()
return JSONResponse(serializer.errors, status=400)
elif request.method == DELETE:
snippet.delete()
return HttpResponse(status=204)
Finally we need to wire these views up. Create the snippets/urls.py file:
from django.conf.urls import patterns, url
urlpatterns = patterns(snippets.views,
url(r^snippets/$, snippet_list),
url(r^snippets/(?P<pk>[0-9]+)/$, snippet_detail),
)
Its worth noting that there are a couple of edge cases were not dealing with properly at the moment. If we send
malformed json, or if a request is made with a method that the view doesnt handle, then well end up with a 500
server error response. Still, thisll do for now.
5.2.9 Testing our first attempt at a Web API

Now we can start up a sample server that serves our snippets.
Quit out of the shell...
quit()
...and start up Djangos development server.

python manage.py runserver
Validating models...
0 errors found
Django version 1.4.3, using settings tutorial.settings
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
In another terminal window, we can test the server.

We can get a list of all of the snippets.
curl http://127.0.0.1:8000/snippets/
[{"id": 1, "title": "", "code": "foo = \"bar\"\n", "linenos": false, "language": "python", "style": "
Or we can get a particular snippet by referencing its id.

curl http://127.0.0.1:8000/snippets/2/
{"id": 2, "title": "", "code": "print \"hello, world\"\n", "linenos": false, "language": "python", "s
Similarly, you can have the same json displayed by visiting these URLs in a web browser.
21
5.2.10 Where are we now

Were doing okay so far, weve got a serialization API that feels pretty similar to Djangos Forms API, and some
regular Django views.
Our API views dont do anything particularly special at the moment, beyond serving json responses, and there are
some error handling edge cases wed still like to clean up, but its a functioning Web API.
Well see how we can start to improve things in part 2 of the tutorial.
5.3 Tutorial 2: Requests and Responses

From this point were going to really start covering the core of REST framework. Lets introduce a couple of essential
building blocks.
5.3.1 Request objects

REST framework introduces a Request object that extends the regular HttpRequest, and provides more flexible
request parsing. The core functionality of the Request object is the request.DATA attribute, which is similar to
request.POST, but more useful for working with Web APIs.
request.POST
request.DATA
# Only handles form data.

# Handles arbitrary data.
Only works for POST method.

Works for POST, PUT and PATCH methods.
5.3.2 Response objects

REST framework also introduces a Response object, which is a type of TemplateResponse that takes unrendered content and uses content negotiation to determine the correct content type to return to the client.
return Response(data)
# Renders to content type as requested by the client.
5.3.3 Status codes

Using numeric HTTP status codes in your views doesnt always make for obvious reading, and its easy to not notice
if you get an error code wrong. REST framework provides more explicit identifiers for each status code, such as
HTTP_400_BAD_REQUEST in the status module. Its a good idea to use these throughout rather than using
numeric identifiers.
5.3.4 Wrapping API views

REST framework provides two wrappers you can use to write API views.
1. The @api_view decorator for working with function based views.
2. The APIView class for working with class based views.
These wrappers provide a few bits of functionality such as making sure you receive Request instances in your view,
and adding context to Response objects so that content negotiation can be performed.
The wrappers also provide behaviour such as returning 405 Method Not Allowed responses when appropriate,
and handling any ParseError exception that occurs when accessing request.DATA with malformed input.
22
Chapter 5. Tutorial
5.3.5 Pulling it all together

Okay, lets go ahead and start using these new components to write a few views.
We dont need our JSONResponse class in views.py anymore, so go ahead and delete that. Once thats done we
can start refactoring our views slightly.
from
from
from
from
from
rest_framework import status

rest_framework.decorators import api_view
rest_framework.response import Response
@api_view([GET, POST])
def snippet_list(request):
"""
List all snippets, or create a new snippet.
"""
return Response(serializer.data)
elif request.method == POST:
serializer = SnippetSerializer(data=request.DATA)
serializer.save()
return Response(serializer.data, status=status.HTTP_201_CREATED)
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
Our instance view is an improvement over the previous example. Its a little more concise, and the code now feels very
similar to if we were working with the Forms API. Were also using named status codes, which makes the response
meanings more obvious.
Here is the view for an individual snippet, in the views.py module.
@api_view([GET, PUT, DELETE])
def snippet_detail(request, pk):
"""
Retrieve, update or delete a snippet instance.
"""
try:
snippet = Snippet.objects.get(pk=pk)
return Response(status=status.HTTP_404_NOT_FOUND)
elif request.method == PUT:
serializer = SnippetSerializer(snippet, data=request.DATA)
serializer.save()
elif request.method == DELETE:
5.3. Tutorial 2: Requests and Responses
23
snippet.delete()
return Response(status=status.HTTP_204_NO_CONTENT)
This should all feel very familiar - it is not a lot different from working with regular Django views.
Notice that were no longer explicitly tying our requests or responses to a given content type. request.DATA can
handle incoming json requests, but it can also handle yaml and other formats. Similarly were returning response
objects with data, but allowing REST framework to render the response into the correct content type for us.
5.3.6 Adding optional format suffixes to our URLs

To take advantage of the fact that our responses are no longer hardwired to a single content type lets add support for
format suffixes to our API endpoints. Using format suffixes gives us URLs that explicitly refer to a given format, and
means our API will be able to handle URLs such as http://example.com/api/items/4.json.
Start by adding a format keyword argument to both of the views, like so.
def snippet_list(request, format=None):
and
def snippet_detail(request, pk, format=None):
Now update the urls.py file slightly, to append a set of format_suffix_patterns in addition to the existing
URLs.
from rest_framework.urlpatterns import format_suffix_patterns
urlpatterns = patterns(snippets.views,
url(r^snippets/$, snippet_list),
url(r^snippets/(?P<pk>[0-9]+)$, snippet_detail),
)
urlpatterns = format_suffix_patterns(urlpatterns)
We dont necessarily need to add these extra url patterns in, but it gives us a simple, clean way of referring to a specific
format.
5.3.7 Hows it looking?

Go ahead and test the API from the command line, as we did in tutorial part 1. Everything is working pretty similarly,
although weve got some nicer error handling if we send invalid requests.
We can get a list of all of the snippets, as before.
curl http://127.0.0.1:8000/snippets/
[{"id": 1, "title": "", "code": "foo = \"bar\"\n", "linenos": false, "language": "python", "style": "
We can control the format of the response that we get back, either by using the Accept header:
curl http://127.0.0.1:8000/snippets/ -H Accept: application/json
curl http://127.0.0.1:8000/snippets/ -H Accept: text/html
# Request JSON
# Request HTML
Or by appending a format suffix:
24
Chapter 5. Tutorial
curl http://127.0.0.1:8000/snippets/.json
curl http://127.0.0.1:8000/snippets/.api
# JSON suffix
# Browsable API suffix
Similarly, we can control the format of the request that we send, using the Content-Type header.
# POST using form data
curl -X POST http://127.0.0.1:8000/snippets/ -d "code=print 123"
{"id": 3, "title": "", "code": "print 123", "linenos": false, "language": "python", "style": "friendl
# POST using JSON

curl -X POST http://127.0.0.1:8000/snippets/ -d {"code": "print 456"} -H "Content-Type: application
{"id": 4, "title": "", "code": "print 456", "linenos": true, "language": "python", "style": "friendly
Now go and open the API in a web browser, by visiting http://127.0.0.1:8000/snippets/.

Browsability
Because the API chooses the content type of the response based on the client request, it will, by default, return an
HTML-formatted representation of the resource when that resource is requested by a web browser. This allows for the
API to return a fully web-browsable HTML representation.
Having a web-browsable API is a huge usability win, and makes developing and using your API much easier. It also
dramatically lowers the barrier-to-entry for other developers wanting to inspect and work with your API.
See the browsable api topic for more information about the browsable API feature and how to customize it.
5.3.8 Whats next?

In tutorial part 3, well start using class based views, and see how generic views reduce the amount of code we need
to write.
5.4 Tutorial 3: Class Based Views

We can also write our API views using class based views, rather than function based views. As well see this is a
powerful pattern that allows us to reuse common functionality, and helps us keep our code DRY.
5.4.1 Rewriting our API using class based views

Well start by rewriting the root view as a class based view. All this involves is a little bit of refactoring of views.py.
from
from
from
from
from
from

django.http import Http404
rest_framework.views import APIView
rest_framework import status
class SnippetList(APIView):
"""
List all snippets, or create a new snippet.
5.4. Tutorial 3: Class Based Views
25
"""
def get(self, request, format=None):
def post(self, request, format=None):
serializer = SnippetSerializer(data=request.DATA)
serializer.save()
return Response(serializer.data, status=status.HTTP_201_CREATED)
So far, so good. It looks pretty similar to the previous case, but weve got better separation between the different HTTP
methods. Well also need to update the instance view in views.py.
class SnippetDetail(APIView):
"""
Retrieve, update or delete a snippet instance.
"""
def get_object(self, pk):
try:
return Snippet.objects.get(pk=pk)
raise Http404
def get(self, request, pk, format=None):
snippet = self.get_object(pk)
def put(self, request, pk, format=None):
serializer = SnippetSerializer(snippet, data=request.DATA)
serializer.save()
def delete(self, request, pk, format=None):
snippet.delete()
return Response(status=status.HTTP_204_NO_CONTENT)
Thats looking good. Again, its still pretty similar to the function based view right now.
Well also need to refactor our urls.py slightly now were using class based views.
from rest_framework.urlpatterns import format_suffix_patterns
from snippets import views
url(r^snippets/$, views.SnippetList.as_view()),
url(r^snippets/(?P<pk>[0-9]+)/$, views.SnippetDetail.as_view()),
)
urlpatterns = format_suffix_patterns(urlpatterns)
26
Chapter 5. Tutorial
Okay, were done. If you run the development server everything should be working just as before.
5.4.2 Using mixins

One of the big wins of using class based views is that it allows us to easily compose reusable bits of behaviour.
The create/retrieve/update/delete operations that weve been using so far are going to be pretty similar for any modelbacked API views we create. Those bits of common behaviour are implemented in REST frameworks mixin classes.
Lets take a look at how we can compose the views by using the mixin classes. Heres our views.py module again.
from
from
from
from

rest_framework import mixins
rest_framework import generics
class SnippetList(mixins.ListModelMixin,
mixins.CreateModelMixin,
generics.GenericAPIView):
queryset = Snippet.objects.all()
serializer_class = SnippetSerializer
def get(self, request, *args, **kwargs):
return self.list(request, *args, **kwargs)
def post(self, request, *args, **kwargs):
return self.create(request, *args, **kwargs)
Well take a moment to examine exactly whats happening here. Were building our view using GenericAPIView,
and adding in ListModelMixin and CreateModelMixin.
The base class provides the core functionality, and the mixin classes provide the .list() and .create() actions.
Were then explicitly binding the get and post methods to the appropriate actions. Simple enough stuff so far.
class SnippetDetail(mixins.RetrieveModelMixin,
mixins.UpdateModelMixin,
mixins.DestroyModelMixin,
generics.GenericAPIView):
return self.retrieve(request, *args, **kwargs)
def put(self, request, *args, **kwargs):
return self.update(request, *args, **kwargs)
def delete(self, request, *args, **kwargs):
return self.destroy(request, *args, **kwargs)
Pretty similar. Again were using the GenericAPIView class to provide the core functionality, and adding in mixins
to provide the .retrieve(), .update() and .destroy() actions.
5.4.3 Using generic class based views

Using the mixin classes weve rewritten the views to use slightly less code than before, but we can go one step further.
REST framework provides a set of already mixed-in generic views that we can use to trim down our views.py
5.4. Tutorial 3: Class Based Views
27
module even more.

from snippets.models import Snippet
from snippets.serializers import SnippetSerializer
from rest_framework import generics
class SnippetList(generics.ListCreateAPIView):
class SnippetDetail(generics.RetrieveUpdateDestroyAPIView):
Wow, thats pretty concise. Weve gotten a huge amount for free, and our code looks like good, clean, idiomatic
Django.
Next well move onto part 4 of the tutorial, where well take a look at how we can deal with authentication and
permissions for our API.
5.5 Tutorial 4: Authentication & Permissions

Currently our API doesnt have any restrictions on who can edit or delete code snippets. Wed like to have some more
advanced behavior in order to make sure that:
Code snippets are always associated with a creator.
Only authenticated users may create snippets.
Only the creator of a snippet may update or delete it.
Unauthenticated requests should have full read-only access.
5.5.1 Adding information to our model

Were going to make a couple of changes to our Snippet model class. First, lets add a couple of fields. One of
those fields will be used to represent the user who created the code snippet. The other field will be used to store the
highlighted HTML representation of the code.
Add the following two fields to the Snippet model in models.py.
owner = models.ForeignKey(auth.User, related_name=snippets)
highlighted = models.TextField()
Wed also need to make sure that when the model is saved, that we populate the highlighted field, using the pygments
code highlighting library.
Well need some extra imports:
from pygments.lexers import get_lexer_by_name
from pygments.formatters.html import HtmlFormatter
from pygments import highlight
And now we can add a .save() method to our model class:
28
Chapter 5. Tutorial
def save(self, *args, **kwargs):

"""
Use the pygments library to create a highlighted HTML
representation of the code snippet.
"""
lexer = get_lexer_by_name(self.language)
linenos = self.linenos and table or False
options = self.title and {title: self.title} or {}
formatter = HtmlFormatter(style=self.style, linenos=linenos,
full=True, **options)
self.highlighted = highlight(self.code, lexer, formatter)
super(Snippet, self).save(*args, **kwargs)
When thats all done well need to update our database tables. Normally wed create a database migration in order to
do that, but for the purposes of this tutorial, lets just delete the database and start again.
rm tmp.db
python ./manage.py syncdb
You might also want to create a few different users, to use for testing the API. The quickest way to do this will be with
the createsuperuser command.
python ./manage.py createsuperuser
5.5.2 Adding endpoints for our User models

Now that weve got some users to work with, wed better add representations of those users to our API. Creating a
new serializer is easy. In serializers.py add:
from django.contrib.auth.models import User
class UserSerializer(serializers.ModelSerializer):
snippets = serializers.PrimaryKeyRelatedField(many=True)
class Meta:
model = User
fields = (id, username, snippets)
Because snippets is a reverse relationship on the User model, it will not be included by default when using the
ModelSerializer class, so we needed to add an explicit field for it.
Well also add a couple of views to views.py. Wed like to just use read-only views for the user representations, so
well use the ListAPIView and RetrieveAPIView generic class based views.
from django.contrib.auth.models import User
class UserList(generics.ListAPIView):
class UserDetail(generics.RetrieveAPIView):
Make sure to also import the UserSerializer class
5.5. Tutorial 4: Authentication & Permissions
29
from snippets.serializers import UserSerializer
Finally we need to add those views into the API, by referencing them from the URL conf. Add the following to the
patterns in urls.py.
url(rûsers/$, views.UserList.as_view()),
url(rûsers/(?P<pk>[0-9]+)/$, views.UserDetail.as_view()),
5.5.3 Associating Snippets with Users

Right now, if we created a code snippet, thered be no way of associating the user that created the snippet, with the
snippet instance. The user isnt sent as part of the serialized representation, but is instead a property of the incoming
request.
The way we deal with that is by overriding a .pre_save() method on our snippet views, that allows us to handle
any information that is implicit in the incoming request or requested URL.
On both the SnippetList and SnippetDetail view classes, add the following method:
def pre_save(self, obj):
obj.owner = self.request.user
5.5.4 Updating our serializer

Now that snippets are associated with the user that created them, lets update our SnippetSerializer to reflect
that. Add the following field to the serializer definition in serializers.py:
owner = serializers.Field(source=owner.username)
Note: Make sure you also add owner, to the list of fields in the inner Meta class.
This field is doing something quite interesting. The source argument controls which attribute is used to populate
a field, and can point at any attribute on the serialized instance. It can also take the dotted notation shown above, in
which case it will traverse the given attributes, in a similar way as it is used with Djangos template language.
The field weve added is the untyped Field class, in contrast to the other typed fields, such as CharField,
BooleanField etc... The untyped Field is always read-only, and will be used for serialized representations,
but will not be used for updating model instances when they are deserialized.
5.5.5 Adding required permissions to views

Now that code snippets are associated with users, we want to make sure that only authenticated users are able to create,
update and delete code snippets.
REST framework includes a number of permission classes that we can use to restrict who can access a given view.
In this case the one were looking for is IsAuthenticatedOrReadOnly, which will ensure that authenticated
requests get read-write access, and unauthenticated requests get read-only access.
First add the following import in the views module
from rest_framework import permissions
Then, add the following property to both the SnippetList and SnippetDetail view classes.
permission_classes = (permissions.IsAuthenticatedOrReadOnly,)
30
Chapter 5. Tutorial
5.5.6 Adding login to the Browsable API

If you open a browser and navigate to the browsable API at the moment, youll find that youre no longer able to create
new code snippets. In order to do so wed need to be able to login as a user.
We can add a login view for use with the browsable API, by editing our URLconf once more.
Add the following import at the top of the file:
from django.conf.urls import include
And, at the end of the file, add a pattern to include the login and logout views for the browsable API.
urlpatterns += patterns(,
url(râpi-auth/, include(rest_framework.urls,
namespace=rest_framework)),
)
The râpi-auth/ part of pattern can actually be whatever URL you want to use. The only restriction is that the
included urls must use the rest_framework namespace.
Now if you open up the browser again and refresh the page youll see a Login link in the top right of the page. If you
log in as one of the users you created earlier, youll be able to create code snippets again.
Once youve created a few code snippets, navigate to the /users/ endpoint, and notice that the representation includes
a list of the snippet pks that are associated with each user, in each users snippets field.
5.5.7 Object level permissions

Really wed like all code snippets to be visible to anyone, but also make sure that only the user that created a code
snippet is able to update or delete it.
To do that were going to need to create a custom permission.
In the snippets app, create a new file, permissions.py
from rest_framework import permissions
class IsOwnerOrReadOnly(permissions.BasePermission):
"""
Custom permission to only allow owners of an object to edit it.
"""
def has_object_permission(self, request, view, obj):
# Read permissions are allowed to any request,
# so well always allow GET, HEAD or OPTIONS requests.
if request.method in permissions.SAFE_METHODS:
return True
# Write permissions are only allowed to the owner of the snippet.
return obj.owner == request.user
Now we can add that custom permission to our snippet instance endpoint, by editing the permission_classes
property on the SnippetDetail class:
permission_classes = (permissions.IsAuthenticatedOrReadOnly,
IsOwnerOrReadOnly,)
Make sure to also import the IsOwnerOrReadOnly class.
5.5. Tutorial 4: Authentication & Permissions
31
from snippets.permissions import IsOwnerOrReadOnly
Now, if you open a browser again, you find that the DELETE and PUT actions only appear on a snippet instance
endpoint if youre logged in as the same user that created the code snippet.
5.5.8 Authenticating with the API

Because we now have a set of permissions on the API, we need to authenticate our requests to it if we want to
edit any snippets. We havent set up any authentication classes, so the defaults are currently applied, which are
SessionAuthentication and BasicAuthentication.
When we interact with the API through the web browser, we can login, and the browser session will then provide the
required authentication for the requests.
If were interacting with the API programmatically we need to explicitly provide the authentication credentials on each
request.
If we try to create a snippet without authenticating, well get an error:
curl -i -X POST http://127.0.0.1:8000/snippets/ -d "code=print 123"
{"detail": "Authentication credentials were not provided."}
We can make a successful request by including the username and password of one of the users we created earlier.
curl -X POST http://127.0.0.1:8000/snippets/ -d "code=print 789" -u tom:password
{"id": 5, "owner": "tom", "title": "foo", "code": "print 789", "linenos": false, "language": "python"
5.5.9 Summary
Weve now got a fairly fine-grained set of permissions on our Web API, and end points for users of the system and for
the code snippets that they have created.
In part 5 of the tutorial well look at how we can tie everything together by creating an HTML endpoint for our
highlighted snippets, and improve the cohesion of our API by using hyperlinking for the relationships within the
system.
5.6 Tutorial 5: Relationships & Hyperlinked APIs

At the moment relationships within our API are represented by using primary keys. In this part of the tutorial well
improve the cohesion and discoverability of our API, by instead using hyperlinking for relationships.
5.6.1 Creating an endpoint for the root of our API

Right now we have endpoints for snippets and users, but we dont have a single entry point to our API. To create
one, well use a regular function-based view and the @api_view decorator we introduced earlier.
from
from
from
from
32
rest_framework import renderers

rest_framework.decorators import api_view
rest_framework.reverse import reverse
Chapter 5. Tutorial
@api_view((GET,))
def api_root(request, format=None):
return Response({
users: reverse(user-list, request=request, format=format),
snippets: reverse(snippet-list, request=request, format=format)
})
Notice that were using REST frameworks reverse function in order to return fully-qualified URLs.
5.6.2 Creating an endpoint for the highlighted snippets

The other obvious thing thats still missing from our pastebin API is the code highlighting endpoints.
Unlike all our other API endpoints, we dont want to use JSON, but instead just present an HTML representation.
There are two styles of HTML renderer provided by REST framework, one for dealing with HTML rendered using
templates, the other for dealing with pre-rendered HTML. The second renderer is the one wed like to use for this
endpoint.
The other thing we need to consider when creating the code highlight view is that theres no existing concrete generic
view that we can use. Were not returning an object instance, but instead a property of an object instance.
Instead of using a concrete generic view, well use the base class for representing instances, and create our own
.get() method. In your snippets.views add:
from rest_framework import renderers
from rest_framework.response import Response
class SnippetHighlight(generics.GenericAPIView):
renderer_classes = (renderers.StaticHTMLRenderer,)
snippet = self.get_object()
return Response(snippet.highlighted)
As usual we need to add the new views that weve created in to our URLconf. Well add a url pattern for our new API
root:
url(r^$, api_root),
And then add a url pattern for the snippet highlights:

url(r^snippets/(?P<pk>[0-9]+)/highlight/$, views.SnippetHighlight.as_view()),
5.6.3 Hyperlinking our API

Dealing with relationships between entities is one of the more challenging aspects of Web API design. There are a
number of different ways that we might choose to represent a relationship:
Using primary keys.
Using hyperlinking between entities.
Using a unique identifying slug field on the related entity.
Using the default string representation of the related entity.
Nesting the related entity inside the parent representation.
5.6. Tutorial 5: Relationships & Hyperlinked APIs
33
Some other custom representation.

REST framework supports all of these styles, and can apply them across forward or reverse relationships, or apply
them across custom managers such as generic foreign keys.
In this case wed like to use a hyperlinked style between entities. In order to do so, well modify our serializers to
extend HyperlinkedModelSerializer instead of the existing ModelSerializer.
The HyperlinkedModelSerializer has the following differences from ModelSerializer:
It does not include the pk field by default.
It includes a url field, using HyperlinkedIdentityField.
Relationships use HyperlinkedRelatedField, instead of PrimaryKeyRelatedField.
We can easily re-write our existing serializers to use hyperlinking.
class SnippetSerializer(serializers.HyperlinkedModelSerializer):
owner = serializers.Field(source=owner.username)
highlight = serializers.HyperlinkedIdentityField(view_name=snippet-highlight, format=html)
class Meta:
model = Snippet
fields = (url, highlight, owner,
title, code, linenos, language, style)
snippets = serializers.HyperlinkedRelatedField(many=True, view_name=snippet-detail)
class Meta:
model = User
fields = (url, username, snippets)
Notice that weve also added a new highlight field. This field is of the same type as the url field, except that
it points to the snippet-highlight url pattern, instead of the snippet-detail url pattern.
Because weve included format suffixed URLs such as .json, we also need to indicate on the highlight field
that any format suffixed hyperlinks it returns should use the .html suffix.
5.6.4 Making sure our URL patterns are named

If were going to have a hyperlinked API, we need to make sure we name our URL patterns. Lets take a look at which
URL patterns we need to name.
The root of our API refers to user-list and snippet-list.
Our snippet serializer includes a field that refers to snippet-highlight.
Our user serializer includes a field that refers to snippet-detail.
Our snippet and user serializers include url fields that by default will refer to
{model_name}-detail, which in this case will be snippet-detail and user-detail.
After adding all those names into our URLconf, our final urls.py file should look something like this:
# API endpoints
urlpatterns = format_suffix_patterns(patterns(snippets.views,
url(r^$, api_root),
url(r^snippets/$,
views.SnippetList.as_view(),
34
Chapter 5. Tutorial
name=snippet-list),
url(r^snippets/(?P<pk>[0-9]+)/$,
views.SnippetDetail.as_view(),
name=snippet-detail),
url(r^snippets/(?P<pk>[0-9]+)/highlight/$,
views.SnippetHighlight.as_view(),
name=snippet-highlight),
url(rûsers/$,
views.UserList.as_view(),
name=user-list),
url(rûsers/(?P<pk>[0-9]+)/$,
views.UserDetail.as_view(),
name=user-detail)
))
# Login and logout views for the browsable API
urlpatterns += patterns(,
url(râpi-auth/, include(rest_framework.urls,
namespace=rest_framework)),
)
5.6.5 Adding pagination

The list views for users and code snippets could end up returning quite a lot of instances, so really wed like to make
sure we paginate the results, and allow the API client to step through each of the individual pages.
We can change the default list style to use pagination, by modifying our settings.py file slightly. Add the following setting:
REST_FRAMEWORK = {
PAGINATE_BY: 10
}
Note that settings in REST framework are all namespaced into a single dictionary setting, named
REST_FRAMEWORK, which helps keep them well separated from your other project settings.
We could also customize the pagination style if we needed too, but in this case well just stick with the default.
5.6.6 Browsing the API

If we open a browser and navigate to the browsable API, youll find that you can now work your way around the API
simply by following links.
Youll also be able to see the highlight links on the snippet instances, that will take you to the highlighted code
HTML representations.
In part 6 of the tutorial well look at how we can use ViewSets and Routers to reduce the amount of code we need to
build our API.
5.7 Tutorial 6: ViewSets & Routers

REST framework includes an abstraction for dealing with ViewSets, that allows the developer to concentrate on
modeling the state and interactions of the API, and leave the URL construction to be handled automatically, based on
common conventions.
5.7. Tutorial 6: ViewSets & Routers
35
ViewSet classes are almost the same thing as View classes, except that they provide operations such as read, or
update, and not method handlers such as get or put.
A ViewSet class is only bound to a set of method handlers at the last moment, when it is instantiated into a set of
views, typically by using a Router class which handles the complexities of defining the URL conf for you.
5.7.1 Refactoring to use ViewSets

Lets take our current set of views, and refactor them into view sets.
First of all lets refactor our UserList and UserDetail views into a single UserViewSet. We can remove the
two views, and replace them with a single class:
from rest_framework import viewsets
class UserViewSet(viewsets.ReadOnlyModelViewSet):
"""
This viewset automatically provides list and detail actions.
"""
Here weve used ReadOnlyModelViewSet class to automatically provide the default read-only operations.
Were still setting the queryset and serializer_class attributes exactly as we did when we were using regular
views, but we no longer need to provide the same information to two separate classes.
Next were going to replace the SnippetList, SnippetDetail and SnippetHighlight view classes. We
can remove the three views, and again replace them with a single class.
from rest_framework.decorators import link
class SnippetViewSet(viewsets.ModelViewSet):
"""
This viewset automatically provides list, create, retrieve,
update and destroy actions.
Additionally we also provide an extra highlight action.
"""
permission_classes = (permissions.IsAuthenticatedOrReadOnly,
IsOwnerOrReadOnly,)
@link(renderer_classes=[renderers.StaticHTMLRenderer])
def highlight(self, request, *args, **kwargs):
snippet = self.get_object()
return Response(snippet.highlighted)
def pre_save(self, obj):
obj.owner = self.request.user
This time weve used the ModelViewSet class in order to get the complete set of default read and write operations.
Notice that weve also used the @link decorator to create a custom action, named highlight. This decorator can
be used to add any custom endpoints that dont fit into the standard create/update/delete style.
Custom actions which use the @link decorator will respond to GET requests. We could have instead used the
@action decorator if we wanted an action that responded to POST requests.
36
Chapter 5. Tutorial
5.7.2 Binding ViewSets to URLs explicitly

The handler methods only get bound to the actions when we define the URLConf. To see whats going on under the
hood lets first explicitly create a set of views from our ViewSets.
In the urls.py file we bind our ViewSet classes into a set of concrete views.
from snippets.views import SnippetViewSet, UserViewSet
from rest_framework import renderers
snippet_list = SnippetViewSet.as_view({
get: list,
post: create
})
snippet_detail = SnippetViewSet.as_view({
get: retrieve,
put: update,
patch: partial_update,
delete: destroy
})
snippet_highlight = SnippetViewSet.as_view({
get: highlight
}, renderer_classes=[renderers.StaticHTMLRenderer])
user_list = UserViewSet.as_view({
get: list
})
user_detail = UserViewSet.as_view({
get: retrieve
})
Notice how were creating multiple views from each ViewSet class, by binding the http methods to the required
action for each view.
Now that weve bound our resources into concrete views, that we can register the views with the URL conf as usual.
urlpatterns = format_suffix_patterns(patterns(snippets.views,
url(r^$, api_root),
url(r^snippets/$, snippet_list, name=snippet-list),
url(r^snippets/(?P<pk>[0-9]+)/$, snippet_detail, name=snippet-detail),
url(r^snippets/(?P<pk>[0-9]+)/highlight/$, snippet_highlight, name=snippet-highlight),
url(rûsers/$, user_list, name=user-list),
url(rûsers/(?P<pk>[0-9]+)/$, user_detail, name=user-detail)
))
5.7.3 Using Routers

Because were using ViewSet classes rather than View classes, we actually dont need to design the URL conf
ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using a Router
class. All we need to do is register the appropriate view sets with a router, and let it do the rest.
Heres our re-wired urls.py file.
from django.conf.urls import patterns, url, include
from snippets import views
from rest_framework.routers import DefaultRouter
# Create a router and register our viewsets with it.
router = DefaultRouter()
5.7. Tutorial 6: ViewSets & Routers
37
router.register(rsnippets, views.SnippetViewSet)
router.register(rusers, views.UserViewSet)
# The API URLs are now determined automatically by the router.
# Additionally, we include the login URLs for the browseable API.
)
Registering the viewsets with the router is similar to providing a urlpattern. We include two arguments - the URL
prefix for the views, and the viewset itself.
The DefaultRouter class were using also automatically creates the API root view for us, so we can now delete
the api_root method from our views module.
5.7.4 Trade-offs between views vs viewsets

Using viewsets can be a really useful abstraction. It helps ensure that URL conventions will be consistent across
your API, minimizes the amount of code you need to write, and allows you to concentrate on the interactions and
representations your API provides rather than the specifics of the URL conf.
That doesnt mean its always the right approach to take. Theres a similar set of trade-offs to consider as when
using class-based views instead of function based views. Using viewsets is less explicit than building your views
individually.
5.7.5 Reviewing our work

With an incredibly small amount of code, weve now got a complete pastebin Web API, which is fully web browseable,
and comes complete with authentication, per-object permissions, and multiple renderer formats.
Weve walked through each step of the design process, and seen how if we need to customize anything we can gradually
work our way down to simply using regular Django views.
You can review the final tutorial code on GitHub, or try out a live example in the sandbox.
5.7.6 Onwards and upwards

Weve reached the end of our tutorial. If you want to get more involved in the REST framework project, heres a few
places you can start:
Contribute on GitHub by reviewing and submitting issues, and making pull requests.
Join the REST framework discussion group, and help build the community.
Follow the author on Twitter and say hi.
Now go build awesome things.
There is a live example API of the finished tutorial API for testing purposes, available here.
38
Chapter 5. Tutorial
CHAPTER 6
API Guide
The API guide is your complete reference manual to all the functionality provided by REST framework.
39
40
Chapter 6. API Guide
CHAPTER 7
Topics
General guides to using REST framework.
7.1 Documenting your API

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for
representing resources and driving application state.
Roy Fielding, REST APIs must be hypertext driven
There are a variety of approaches to API documentation. This document introduces a few of the various tools and
options you might choose from. The approaches should not be considered exclusive - you may want to provide more
than one documentation style for you API, such as a self describing API that also includes static documentation of the
various API endpoints.
7.1.1 Endpoint documentation

The most common way to document Web APIs today is to produce documentation that lists the API endpoints verbatim, and describes the allowable operations on each. There are various tools that allow you to do this in an automated
or semi-automated way.
Django REST Swagger

Marc Gibbons Django REST Swagger integrates REST framework with the Swagger API documentation tool. The
package produces well presented API documentation, and includes interactive tools for testing API endpoints.
The package is fully documented, well supported, and comes highly recommended.
Django REST Swagger supports REST framework versions 2.3 and above.
REST Framework Docs

The REST Framework Docs package is an earlier project, also by Marc Gibbons, that offers clean, simple autogenerated documentation for your API.
41
Figure 7.1: Screenshot - Django REST Swagger

Apiary
There are various other online tools and services for providing API documentation. One notable service is Apiary.
With Apiary, you describe your API using a simple markdown-like syntax. The generated documentation includes
API interaction, a mock server for testing & prototyping, and various other tools.
7.1.2 Self describing APIs

The browsable API that REST framework provides makes it possible for your API to be entirely self describing. The
documentation for each API endpoint can be provided simply by visiting the URL in your browser.
Setting the title

The title that is used in the browsable API is generated from the view class name or function name. Any trailing
View or ViewSet suffix is stripped, and the string is whitespace separated on uppercase/lowercase boundaries or
underscores.
For example, the view UserListView, will be named User List when presented in the browsable API.
When working with viewsets, an appropriate suffix is appended to each generated view. For example, the view set
UserViewSet will generate views named User List and User Instance.
Setting the description
The description in the browsable API is generated from the docstring of the view or viewset.
42
Chapter 7. Topics
Figure 7.2: Screenshot - REST Framework Docs
7.1. Documenting your API
43
Figure 7.3: Screenshot - Apiary
Figure 7.4: Screenshot - Self describing API
44
Chapter 7. Topics
If the python markdown library is installed, then markdown syntax may be used in the docstring, and will be converted
to HTML in the browsable API. For example:
class AccountListView(views.APIView):
"""
Returns a list of all **active** accounts in the system.
For more details on how accounts are activated please [see here][ref].
[ref]: http://example.com/activating-accounts
"""
Note that one constraint of using viewsets is that any documentation be used for all generated views, so for example,
you cannot have differing documentation for the generated list view and detail view.
The OPTIONS method
REST framework APIs also support programmatically accessible descriptions, using the OPTIONS HTTP method. A
view will respond to an OPTIONS request with metadata including the name, description, and the various media types
it accepts and responds with.
When using the generic views, any OPTIONS requests will additionally respond with metadata regarding any POST
or PUT actions available, describing which fields are on the serializer.
You can modify the response behavior to OPTIONS requests by overriding the metadata view method. For example:
def metadata(self, request):
"""
Dont include the view description in OPTIONS responses.
"""
data = super(ExampleView, self).metadata(request)
data.pop(description)
return data
7.1.3 The hypermedia approach

To be fully RESTful an API should present its available actions as hypermedia controls in the responses that it sends.
In this approach, rather than documenting the available API endpoints up front, the description instead concentrates
on the media types that are used. The available actions take may be taken on any given URL are not strictly fixed, but
are instead made available by the presence of link and form controls in the returned document.
To implement a hypermedia API youll need to decide on an appropriate media type for the API, and implement a
custom renderer and parser for that media type. The REST, Hypermedia & HATEOAS section of the documentation
includes pointers to background reading, as well as links to various hypermedia formats.
7.2 Working with AJAX, CSRF & CORS

Take a close look at possible CSRF / XSRF vulnerabilities on your own websites. Theyre the worst kind
of vulnerability very easy to exploit by attackers, yet not so intuitively easy to understand for software
developers, at least until youve been bitten by one.
Jeff Atwood
7.2. Working with AJAX, CSRF & CORS
45
7.2.1 Javascript clients

If youre building a JavaScript client to interface with your Web API, youll need to consider if the client can use the
same authentication policy that is used by the rest of the website, and also determine if you need to use CSRF tokens
or CORS headers.
AJAX requests that are made within the same context as the API they are interacting with will typically use
SessionAuthentication. This ensures that once a user has logged in, any AJAX requests made can be authenticated using the same session-based authentication that is used for the rest of the website.
AJAX requests that are made on a different site from the API they are communicating with will typically need to use
a non-session-based authentication scheme, such as TokenAuthentication.
7.2.2 CSRF protection

Cross Site Request Forgery protection is a mechanism of guarding against a particular type of attack, which can occur
when a user has not logged out of a web site, and continues to have a valid session. In this circumstance a malicious
site may be able to perform actions against the target site, within the context of the logged-in session.
To guard against these type of attacks, you need to do two things:
1. Ensure that the safe HTTP operations, such as GET, HEAD and OPTIONS cannot be used to alter any serverside state.
2. Ensure that any unsafe HTTP operations, such as POST, PUT, PATCH and DELETE, always require a valid
CSRF token.
If youre using SessionAuthentication youll need to include valid CSRF tokens for any POST, PUT, PATCH
or DELETE operations.
In order to make AJAX requests, you need to include CSRF token in the HTTP header, as described in the Django
documentation.
7.2.3 CORS
Cross-Origin Resource Sharing is a mechanism for allowing clients to interact with APIs that are hosted on a different
domain. CORS works by requiring the server to include a specific set of headers that allow a browser to determine if
and when cross-domain requests should be allowed.
The best way to deal with CORS in REST framework is to add the required response headers in middleware. This
ensures that CORS is supported transparently, without having to change any behavior in your views.
Otto Yiu maintains the django-cors-headers package, which is known to work correctly with REST framework APIs.
7.3 Browser enhancements

There are two noncontroversial uses for overloaded POST. The first is to simulate HTTPs uniform
interface for clients like web browsers that dont support PUT or DELETE
RESTful Web Services, Leonard Richardson & Sam Ruby.
46
Chapter 7. Topics
7.3.1 Browser based PUT, DELETE, etc...

REST framework supports browser-based PUT, DELETE and other methods, by overloading POST requests using a
hidden form field.
Note that this is the same strategy as is used in Ruby on Rails.
For example, given the following form:
<form action="/news-items/5" method="POST">
<input type="hidden" name="_method" value="DELETE">
</form>
request.method would return "DELETE".
7.3.2 HTTP header based method overriding

REST framework also supports method overriding via the semi-standard X-HTTP-Method-Override header.
This can be useful if you are working with non-form content such as JSON and are working with an older web server
and/or hosting provider that doesnt recognise particular HTTP methods such as PATCH. For example Amazon Web
Services ELB.
To use it, make a POST request, setting the X-HTTP-Method-Override header.
For example, making a PATCH request via POST in jQuery:
$.ajax({
url: /myresource/,
method: POST,
headers: {X-HTTP-Method-Override: PATCH},
...
});
7.3.3 Browser based submission of non-form content

Browser-based submission of content types other than form are supported by using form fields named _content and
_content_type:
For example, given the following form:
<form action="/news-items/5" method="PUT">
<input type="hidden" name="_content_type" value="application/json">
<input name="_content" value="{count: 1}">
</form>
request.content_type would return "application/json", and request.stream would return

"{count: 1}"
7.3.4 URL based accept headers

REST framework can take ?accept=application/json style URL parameters, which allow the Accept
header to be overridden.
This can be useful for testing the API from a web browser, where you dont have any control over what is sent in the
Accept header.
7.3. Browser enhancements
47
7.3.5 URL based format suffixes

REST framework can take ?format=json style URL parameters, which can be a useful shortcut for determining
which content type should be returned from the view.
This is a more concise than using the accept override, but it also gives you less control. (For example you cant
specify any media type parameters)
7.3.6 Doesnt HTML5 support PUT and DELETE forms?

Nope. It was at one point intended to support PUT and DELETE forms, but was later dropped from the spec. There
remains ongoing discussion about adding support for PUT and DELETE, as well as how to support content types other
than form-encoded data.
7.4 The Browsable API

It is a profoundly erroneous truism... that we should cultivate the habit of thinking of what we are doing.
The precise opposite is the case. Civilization advances by extending the number of important operations
which we can perform without thinking about them.
Alfred North Whitehead, An Introduction to Mathematics (1911)
API may stand for Application Programming Interface, but humans have to be able to read the APIs, too; someone
has to do the programming. Django REST Framework supports generating human-friendly HTML output for each
resource when the HTML format is requested. These pages allow for easy browsing of resources, as well as forms for
submitting data to the resources using POST, PUT, and DELETE.
7.4.1 URLs
If you include fully-qualified URLs in your resource output, they will be urlized and made clickable for easy browsing
by humans. The rest_framework package includes a reverse <../api-guide/reverse.md>_ helper for this
purpose.
7.4.2 Formats
By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The
format can be specified using ?format= in the request, so you can look at the raw JSON response in a browser by
adding ?format=json to the URL. There are helpful extensions for viewing JSON in Firefox and Chrome.
7.4.3 Customizing
The browsable API is built with Twitters Bootstrap (v 2.1.1), making it easy to customize the look-and-feel.
To customize the default style, create a template called rest_framework/api.html that extends from
rest_framework/base.html. For example:
templates/rest_framework/api.html
{% extends "rest_framework/base.html" %}
...
48
# Override blocks with required customizations
Chapter 7. Topics
Overriding the default theme

To replace the default theme, add a bootstrap_theme block to your api.html and insert a link to the desired
Bootstrap theme css file. This will completely replace the included theme.
{% block bootstrap_theme %}
<link rel="stylesheet" href="/path/to/my/bootstrap.css" type="text/css">
{% endblock %}
A suitable replacement theme can be generated using Bootstraps Customize Tool. There are also pre-made themes
available at Bootswatch. To use any of the Bootswatch themes, simply download the themes bootstrap.min.css
file, add it to your project, and replace the default one as described above.
You can also change the navbar variant, which by default is navbar-inverse, using the
bootstrap_navbar_variant block. The empty {% block bootstrap_navbar_variant %}{%
endblock %} will use the original Bootstrap navbar style.
Full example:
{% extends "rest_framework/base.html" %}
{% block bootstrap_theme %}
<link rel="stylesheet" href="http://bootswatch.com/flatly/bootstrap.min.css" type="text/css">
{% endblock %}
{% block bootstrap_navbar_variant %}{% endblock %}
For more specific CSS tweaks than simply overriding the default bootstrap theme you can override the style block.
Figure 7.5: Cerulean theme
7.4. The Browsable API
49
Screenshot of the bootswatch Cerulean theme
Figure 7.6: Slate theme

Screenshot of the bootswatch Slate theme
Blocks
All of the blocks available in the browsable API base template that can be used in your api.html.
bodyclass - Class attribute for the <body> tag, empty by default.
bootstrap_theme - CSS for the Bootstrap theme.
bootstrap_navbar_variant - CSS class for the navbar.
branding - Branding section of the navbar, see Bootstrap components.
breadcrumbs - Links showing resource nesting, allowing the user to go back up the resources. Its recommended to preserve these, but they can be overridden using the breadcrumbs block.
footer - Any copyright notices or similar footer materials can go here (by default right-aligned).
script - JavaScript files for the page.
style - CSS stylesheets for the page.
title - Title of the page.
userlinks - This is a list of links on the right of the header, by default containing login/logout links. To add
links instead of replace, use {{ block.super }} to preserve the authentication links.
50
Chapter 7. Topics
Components
All of the standard Bootstrap components are available.

Tooltips
The browsable API makes use of the Bootstrap tooltips component. Any element with the js-tooltip class and a
title attribute has that title content will display a tooltip on hover events.
Login Template
To add branding and customize the look-and-feel of the login template, create a template called login.html and
add it to your project, eg: templates/rest_framework/login.html. The template should extend from
rest_framework/login_base.html.
You can add your site name or branding by including the branding block:
{% block branding %}
<h3 style="margin: 0 0 20px;">My Site Name</h3>
{% endblock %}
You can also customize the style by adding the bootstrap_theme or style block similar to api.html.
Advanced Customization
Context
The context thats available to the template:

allowed_methods : A list of methods allowed by the resource
api_settings : The API settings
available_formats : A list of formats allowed by the resource
breadcrumblist : The list of links following the chain of nested resources
content : The content of the API response
description : The description of the resource, generated from its docstring
name : The name of the resource
post_form : A form instance for use by the POST form (if allowed)
put_form : A form instance for use by the PUT form (if allowed)
display_edit_forms : A boolean indicating whether or not POST, PUT and PATCH forms will be displayed
request : The request object
response : The response object
version : The version of Django REST Framework
view : The view handling the request
FORMAT_PARAM : The view can accept a format override
7.4. The Browsable API
51
METHOD_PARAM : The view can accept a method override

You can override the BrowsableAPIRenderer.get_context() method to customise the context that gets
passed to the template.
Not using base.html
For more advanced customization, such as not having a Bootstrap basis or tighter integration with the rest of your
site, you can simply choose not to have api.html extend base.html. Then the page content and capabilities are
entirely up to you.
Autocompletion
When a ChoiceField has too many items, rendering the widget containing all the options can become very slow,
and cause the browsable API rendering to perform poorly. One solution is to replace the selector by an autocomplete
widget, that only loads and renders a subset of the available options as needed.
There are a variety of packages for autocomplete widgets, such as django-autocomplete-light. To setup
django-autocomplete-light, follow the installation documentation, add the the following to the api.html
template:
{%
{{
{%
{%
block script %}
block.super }}
include autocomplete_light/static.html %}
endblock %}
You can now add the autocomplete_light.ChoiceWidget widget to the serializer field.
import autocomplete_light
class BookSerializer(serializers.ModelSerializer):
author = serializers.ChoiceField(
widget=autocomplete_light.ChoiceWidget(AuthorAutocomplete)
)
class Meta:
model = Book
Screenshot of the autocomplete-light widget
7.5 REST, Hypermedia & HATEOAS

You keep using that word REST. I do not think it means what you think it means.
Mike Amundsen, REST fest 2012 keynote.
First off, the disclaimer. The name Django REST framework was chosen simply to sure the project would be easily
found by developers. Throughout the documentation we try to use the more simple and technically correct terminology
of Web APIs.
If you are serious about designing a Hypermedia APIs, you should look to resources outside of this documentation to
help inform your design choices.
The following fall into the required reading category.
52
Chapter 7. Topics
Figure 7.7: Autocomplete

Roy Fieldings dissertation - Architectural Styles and the Design of Network-based Software Architectures.
Roy Fieldings REST APIs must be hypertext-driven blog post.
Leonard Richardson & Sam Rubys RESTful Web Services.
Mike Amundsens Building Hypermedia APIs with HTML5 and Node.
Steve Klabniks Designing Hypermedia APIs.
The Richardson Maturity Model.
For a more thorough background, check out Klabniks Hypermedia API reading list.
7.5.1 Building Hypermedia APIs with REST framework

REST framework is an agnostic Web API toolkit. It does help guide you towards building well-connected APIs, and
makes it easy to design appropriate media types, but it does not strictly enforce any particular design style.
7.5.2 What REST framework provides.

It is self evident that REST framework makes it possible to build Hypermedia APIs. The browsable API that it offers
is built on HTML - the hypermedia language of the web.
REST framework also includes serialization and parser/renderer components that make it easy to build appropriate
media types, hyperlinked relations for building well-connected systems, and great support for content negotiation.
7.5. REST, Hypermedia & HATEOAS
53
7.5.3 What REST framework doesnt provide.

What REST framework doesnt do is give you is machine readable hypermedia formats such as HAL, Collection+JSON, JSON API or HTML microformats by default, or the ability to auto-magically create fully HATEOAS
style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks. Doing so would
involve making opinionated choices about API design that should really remain outside of the frameworks scope.
7.6 Contributing to REST framework

The world can only really be changed one piece at a time. The art is picking that piece.
Tim Berners-Lee
There are many ways you can contribute to Django REST framework. Wed like it to be a community-led project, so
please get involved and help shape the future of the project.
7.6.1 Community
The most important thing you can do to help push the REST framework project forward is to be actively involved
wherever possible. Code contributions are often overvalued as being the primary way to get involved in a project, we
dont believe that needs to be the case.
If you use REST framework, wed love you to be vocal about your experiences with it - you might consider writing a
blog post about using REST framework, or publishing a tutorial about building a project with a particular Javascript
framework. Experiences from beginners can be particularly helpful because youll be in the best position to assess
which bits of REST framework are more difficult to understand and work with.
Other really great ways you can help move the community forward include helping answer questions on the discussion group, or setting up an email alert on StackOverflow so that you get notified of any new questions with the
django-rest-framework tag.
When answering questions make sure to help future contributors find their way around by hyperlinking wherever
possible to related threads and tickets, and include backlinks from those items if relevant.
7.6.2 Code of conduct

Please keep the tone polite & professional. For some users a discussion on the REST framework mailing list or ticket
tracker may be their first engagement with the open source community. First impressions count, so lets try to make
everyone feel welcome.
Be mindful in the language you choose. As an example, in an environment that is heavily male-dominated, posts that
start Hey guys, can come across as unintentionally exclusive. Its just as easy, and more inclusive to use gender
neutral language in those situations.
The Django code of conduct gives a fuller set of guidelines for participating in community forums.
7.7 Issues
Its really helpful if you can make sure to address issues on the correct channel. Usage questions should be directed to
the discussion group. Feature requests, bug reports and other issues should be raised on the GitHub issue tracker.
Some tips on good issue reporting:
54
Chapter 7. Topics
When describing issues try to phrase your ticket in terms of the behavior you think needs changing rather than
the code you think need changing.
Search the issue list first for related items, and make sure youre running the latest version of REST framework
before reporting an issue.
If reporting a bug, then try to include a pull request with a failing test case. This will help us quickly identify if
there is a valid issue, and make sure that it gets fixed more quickly if there is one.
Feature requests will often be closed with a recommendation that they be implemented outside of the core REST
framework library. Keeping new feature requests implemented as third party libraries allows us to keep down
the maintainence overhead of REST framework, so that the focus can be on continued stability, bugfixes, and
great documentation.
Closing an issue doesnt necessarily mean the end of a discussion. If you believe your issue has been closed
incorrectly, explain why and well consider if it needs to be reopened.
7.7.1 Triaging issues

Getting involved in triaging incoming issues is a good way to start contributing. Every single ticket that comes into
the ticket tracker needs to be reviewed in order to determine what the next steps should be. Anyone can help out with
this, you just need to be willing to
Read through the ticket - does it make sense, is it missing any context that would help explain it better?
Is the ticket reported in the correct place, would it be better suited as a discussion on the discussion group?
If the ticket is a bug report, can you reproduce it? Are you able to write a failing test case that demonstrates the
issue and that can be submitted as a pull request?
If the ticket is a feature request, do you agree with it, and could the feature request instead be implemented as a
third party package?
If a ticket hasnt had much activity and it addresses something you need, then comment on the ticket and try to
find out whats needed to get it moving again.
7.8 Development
To start developing on Django REST framework, clone the repo:
git clone git@github.com:tomchristie/django-rest-framework.git
Changes should broadly follow the PEP 8 style conventions, and we recommend you setup your editor to automatically
indicated non-conforming styles.
7.8.1 Testing
To run the tests, clone the repository, and then:
# Setup the virtual environment
virtualenv env
source env/bin/activate
pip install -r requirements.txt
pip install -r optionals.txt
# Run the tests
rest_framework/runtests/runtests.py
7.8. Development
55
You can also use the excellent [tox][tox] testing tool to run the tests against all supported versions of Python and
Django. Install tox globally, and then simply run:
tox
7.8.2 Pull requests

Its a good idea to make pull requests early on. A pull request represents the start of a discussion, and doesnt
necessarily need to be the final, finished submission.
Its also always best to make a new branch before starting work on a pull request. This means that youll be able to
later switch back to working on another seperate issue without interfering with an ongoing pull requests.
Its also useful to remember that if you have an outstanding pull request then pushing new commits to your GitHub
repo will also automatically update the pull requests.
GitHubs documentation for working on pull requests is available here.
Always run the tests before submitting pull requests, and ideally run tox in order to check that your modifications are
compatible with both Python 2 and Python 3, and that they run properly on all supported versions of Django.
Once youve made a pull request take a look at the travis build status in the GitHub interface and make sure the tests
are runnning as youd expect.
Figure 7.8: Travis status

Above: Travis build notifications
7.8.3 Managing compatibility issues

Sometimes, in order to ensure your code works on various different versions of Django, Python or third party libraries,
youll need to run slightly different code depending on the environment. Any code that branches in this way should
be isolated into the compat.py module, and should provide a single common interface that the rest of the codebase
can use.
7.9 Documentation
The documentation for REST framework is built from the Markdown source files in the docs directory.
There are many great markdown editors that make working with the documentation really easy. The Mou editor for
Mac is one such editor that comes highly recommended.
56
Chapter 7. Topics
7.9.1 Building the documentation

To build the documentation, simply run the mkdocs.py script.
./mkdocs.py
This will build the html output into the html directory.
You can build the documentation and open a preview in a browser window by using the -p flag.
./mkdocs.py -p
7.9.2 Language style

Documentation should be in American English. The tone of the documentation is very important - try to stick to a
simple, plain, objective and well-balanced style where possible.
Some other tips:
Keep paragraphs reasonably short.
Use double spacing after the end of sentences.
Dont use the abbreviations such as e.g. but instead use long form, such as For example.
7.9.3 Markdown style

There are a couple of conventions you should follow when working on the documentation.
1. Headers
Headers should use the hash style. For example:
### Some important topic
The underline style should not be used. Dont do this:

Some important topic
====================
2. Links
Links should always use the reference style, with the referenced hyperlinks kept at the end of the document.
Here is a link to [some other thing][other-thing].
More text...
[other-thing]: http://example.com/other/thing
This style helps keep the documentation source consistent and readable.
If you are hyperlinking to another REST framework document, you should use a relative link, and link to the .md
suffix. For example:
7.9. Documentation
57
[authentication]: ../api-guide/authentication.md
Linking in this style means youll be able to click the hyperlink in your markdown editor to open the referenced
document. When the documentation is built, these links will be converted into regular links to HTML pages.
3. Notes
If you want to draw attention to a note or warning, use a pair of enclosing lines, like so:
--**Note:** A useful documentation note.
---
7.10 Third party packages

New features to REST framework are generally recommended to be implemented as third party libraries that are
developed outside of the core framework. Ideally third party libraries should be properly documented and packaged,
and made available on PyPI.
7.10.1 Getting started

If you have some functionality that you would like to implement as a third party package its worth contacting the
discussion group as others may be willing to get involved. We strongly encourage third party package development
and will always try to prioritize time spent helping their development, documentation and packaging.
We recommend the django-reusable-app <https://github.com/dabapps/django-reusable-app>_ template as a
good resource for getting up and running with implementing a third party Django package.
7.10.2 Linking to your package

Once your package is decently documented and available on PyPI open a pull request or issue, and well add a link to
it from the main REST framework documentation.
7.11 Django REST framework 2

What it is, and why you should care.
Most people just make the mistake that it should be simple to design simple things. In reality, the effort
required to design something is inversely proportional to the simplicity of the result.
Roy Fielding
Announcement: REST framework 2 released - Tue 30th Oct 2012
REST framework 2 is an almost complete reworking of the original framework, which comprehensively addresses
some of the original design issues.
58
Chapter 7. Topics
Because the latest version should be considered a re-release, rather than an incremental improvement, weve skipped
a version, and called this release Django REST framework 2.0.
This article is intended to give you a flavor of what REST framework 2 is, and why you might want to give it a try.
7.11.1 User feedback

Before we get cracking, lets start with the hard sell, with a few bits of feedback from some early adopters. . .
Django REST framework 2 is beautiful. Some of the API design is worthy of @kennethreitz. - Kit La Touche
Since its pretty much just Django, controlling things like URLs has been a breeze... I think [REST framework 2]
has definitely got the right approach here; even simple things like being able to override a function called post to do
custom work during rather than having to intimately know what happens during a post make a huge difference to your
productivity. - Ian Strachan
I switched to the 2.0 branch and I dont regret it - fully refactored my code in another &half; day and its much more
to my tastes - Bruno Desthuilliers
Sounds good, right? Lets get into some details...
7.11.2 Serialization
REST framework 2 includes a totally re-worked serialization engine, that was initially intended as a replacement for
Djangos existing inflexible fixture serialization, and which meets the following design goals:
A declarative serialization API, that mirrors Djangos Forms/ModelForms API.
Structural concerns are decoupled from encoding concerns.
Able to support rendering and parsing to many formats, including both machine-readable representations and
HTML forms.
Validation that can be mapped to obvious and comprehensive error responses.
Serializers that support both nested, flat, and partially-nested representations.
Relationships that can be expressed as primary keys, hyperlinks, slug fields, and other custom representations.
Mapping between the internal state of the system and external representations of that state is the core concern of building Web APIs. Designing serializers that allow the developer to do so in a flexible and obvious way is a deceptively
difficult design task, and with the new serialization API we think weve pretty much nailed it.
7.11.3 Generic views

When REST framework was initially released at the start of 2011, the current Django release was version 1.2. REST
framework included a backport of Django 1.3s upcoming View class, but it didnt take full advantage of the generic
view implementations.
With the new release the generic views in REST framework now tie in with Djangos generic views. The end result is
that framework is clean, lightweight and easy to use.
7.11.4 Requests, Responses & Views

REST framework 2 includes Request and Response classes, than are used in place of Djangos existing
HttpRequest and HttpResponse classes. Doing so allows logic such as parsing the incoming request or rendering the outgoing response to be supported transparently by the framework.
7.11. Django REST framework 2
59
The Request/Response approach leads to a much cleaner API, less logic in the view itself, and a simple, obvious
request-response cycle.
REST framework 2 also allows you to work with both function-based and class-based views. For simple API views
all you need is a single @api_view decorator, and youre good to go.
7.11.5 API Design

Pretty much every aspect of REST framework has been reworked, with the aim of ironing out some of the design
flaws of the previous versions. Each of the components of REST framework are cleanly decoupled, and can be used
independently of each-other, and there are no monolithic resource classes, overcomplicated mixin combinations, or
opinionated serialization or URL routing decisions.
7.11.6 The Browsable API

Django REST frameworks most unique feature is the way it is able to serve up both machine-readable representations,
and a fully browsable HTML representation to the same endpoints.
Browsable Web APIs are easier to work with, visualize and debug, and generally makes it easier and more frictionless
to inspect and work with.
With REST framework 2, the browsable API gets a snazzy new bootstrap-based theme that looks great and is even
nicer to work with.
There are also some functionality improvements - actions such as as POST and DELETE will only display if the user
has the appropriate permissions.
Image above: An example of the browsable API in REST framework 2
7.11.7 Documentation
As you can see the documentation for REST framework has been radically improved. It gets a completely new style,
using markdown for the documentation source, and a bootstrap-based theme for the styling.
Were really pleased with how the docs style looks - its simple and clean, is easy to navigate around, and we think it
reads great.
7.11.8 Summary
In short, weve engineered the hell outta this thing, and were incredibly proud of the result.
If youre interested please take a browse around the documentation. The tutorial is a great place to get started.
Theres also a live sandbox version of the tutorial API available for testing.
7.12 REST framework 2.2 announcement

The 2.2 release represents an important point for REST framework, with the addition of Python 3 support, and the
introduction of an official deprecation policy.
60
Chapter 7. Topics
Figure 7.9: Browsable API
7.12. REST framework 2.2 announcement
61
7.12.1 Python 3 support

Thanks to some fantastic work from Xavier Ordoquy, Django REST framework 2.2 now supports Python 3. Youll
need to be running Django 1.5, and its worth keeping in mind that Djangos Python 3 support is currently considered
experimental.
Django 1.6s Python 3 support is expected to be officially labeled as production-ready.
If you want to start ensuring that your own projects are Python 3 ready, we can highly recommend Djangos Porting
to Python 3 documentation.
Django REST frameworks Python 2.6 support now requires 2.6.5 or above, in line with Django 1.5s Python compatibility.
7.12.2 Deprecation policy

Weve now introduced an official deprecation policy, which is in line with Djangos deprecation policy. This policy
will make it easy for you to continue to track the latest, greatest version of REST framework.
The timeline for deprecation works as follows:
Version 2.2 introduces some API changes as detailed in the release notes. It remains fully backwards compatible
with 2.1, but will raise PendingDeprecationWarning warnings if you use bits of API that are due to
be deprecated. These warnings are silent by default, but can be explicitly enabled when youre ready to start
migrating any required changes. For example if you start running your tests using python -Wd manage.py
test, youll be warned of any API changes you need to make.
Version 2.3 will escalate these warnings to DeprecationWarning, which is loud by default.
Version 2.4 will remove the deprecated bits of API entirely.
Note that in line with Djangos policy, any parts of the framework not mentioned in the documentation should generally
be considered private API, and may be subject to change.
7.12.3 Community
As of the 2.2 merge, weve also hit an impressive milestone. The number of committers listed in the credits, is now at
over one hundred individuals. Each name on that list represents at least one merged pull request, however large or
small.
Our mailing list and #restframework IRC channel are also very active, and weve got a really impressive rate of
development both on REST framework itself, and on third party packages such as the great django-rest-frameworkdocs package from Marc Gibbons.
7.12.4 API changes

The 2.2 release makes a few changes to the API, in order to make it more consistent, simple, and easier to use.
Cleaner to-many related fields
The ManyRelatedField() style is being deprecated in favor of a new RelatedField(many=True) syntax.
For example, if a user is associated with multiple questions, which we want to represent using a primary key relationship, we might use something like the following:
62
Chapter 7. Topics
questions = serializers.PrimaryKeyRelatedField(many=True)
class Meta:
fields = (username, questions)
The new syntax is cleaner and more obvious, and the change will also make the documentation cleaner, simplify the
internal API, and make writing custom relational fields easier.
The change also applies to serializers. If you have a nested serializer, you should start using many=True for tomany relationships. For example, a serializer representation of an Album that can contain many Tracks might look
something like this:
class TrackSerializer(serializer.ModelSerializer):
class Meta:
model = Track
fields = (name, duration)
class AlbumSerializer(serializer.ModelSerializer):
tracks = TrackSerializer(many=True)
class Meta:
model = Album
fields = (album_name, artist, tracks)
Additionally, the change also applies when serializing or deserializing data. For example to serialize a queryset of
models you should now use the many=True flag.
serializer = SnippetSerializer(Snippet.objects.all(), many=True)
serializer.data
This more explicit behavior on serializing and deserializing data makes integration with non-ORM backends such
as MongoDB easier, as instances to be serialized can include the __iter__ method, without incorrectly triggering
list-based serialization, or requiring workarounds.
The implicit to-many behavior on serializers, and the ManyRelatedField style classes will continue to function,
but will raise a PendingDeprecationWarning, which can be made visible using the -Wd flag.
Note: If you need to forcibly turn off the implicit many=True for __iter__ objects behavior, you can now
do so by specifying many=False. This will become the default (instead of the current default of None) once the
deprecation of the implicit behavior is finalised in version 2.4.
Cleaner optional relationships
Serializer relationships for nullable Foreign Keys will change from using the current null=True flag, to instead
using required=False.
For example, is a user account has an optional foreign key to a company, that you want to express using a hyperlink,
you might use the following field in a Serializer class:
current_company = serializers.HyperlinkedRelatedField(required=False)
This is in line both with the rest of the serializer fields API, and with Djangos Form and ModelForm API.
Using required throughout the serializers API means you wont need to consider if a particular field should take
blank or null arguments instead of required, and also means there will be more consistent behavior for how
fields are treated when they are not present in the incoming data.
63
The null=True argument will continue to function, and will imply required=False, but will raise a
PendingDeprecationWarning.
Cleaner CharField syntax
The CharField API previously took an optional blank=True argument, which was intended to differentiate
between null CharField input, and blank CharField input.
In keeping with Djangos CharField API, REST frameworks CharField will only ever return the empty string,
for missing or None inputs. The blank flag will no longer be in use, and you should instead just use the
required=<bool> flag. For example:
extra_details = CharField(required=False)
The blank keyword argument will continue to function, but will raise a PendingDeprecationWarning.
Simpler object-level permissions
Custom permissions classes previously used the signature .has_permission(self, request, view,
obj=None). This method would be called twice, firstly for the global permissions check, with the obj parameter set to None, and again for the object-level permissions check when appropriate, with the obj parameter set to the
relevant model instance.
The global permissions check and object-level permissions check are now separated into two separate methods, which
gives a cleaner, more obvious API.
Global permission checks now use the .has_permission(self, request, view) signature.
Object-level permission checks use a new method .has_object_permission(self, request,
view, obj).
For example, the following custom permission class:
class IsOwner(permissions.BasePermission):
"""
Custom permission to only allow owners of an object to view or edit it.
Model instances are expected to include an owner attribute.
"""
def has_permission(self, request, view, obj=None):
if obj is None:
# Ignore global permissions check
return True
Now becomes:
class IsOwner(permissions.BasePermission):
"""
Custom permission to only allow owners of an object to view or edit it.
Model instances are expected to include an owner attribute.
"""
def has_object_permission(self, request, view, obj):
64
Chapter 7. Topics
If youre overriding the BasePermission class, the old-style signature will continue to function, and will correctly
handle both global and object-level permissions checks, but its use will raise a PendingDeprecationWarning.
Note also that the usage of the internal APIs for permission checking on the View class has been cleaned up slightly,
and is now documented and subject to the deprecation policy in all future versions.
More explicit hyperlink relations behavior
When using a serializer with a HyperlinkedRelatedField or HyperlinkedIdentityField, the hyperlinks would previously use absolute URLs if the serializer context included a request key, and fall back to using
relative URLs otherwise. This could lead to non-obvious behavior, as it might not be clear why some serializers
generated absolute URLs, and others do not.
From version 2.2 onwards, serializers with hyperlinked relationships always require a request key to be
supplied in the context dictionary. The implicit behavior will continue to function, but its use will raise a
7.13 REST framework 2.3 announcement

REST framework 2.3 makes it even quicker and easier to build your Web APIs.
7.13.1 ViewSets and Routers

The 2.3 release introduces the ViewSet and Router classes.
A viewset is simply a type of class based view that allows you to group multiple views into a single common class.
Routers allow you to automatically determine the URLconf for your viewset classes.
As an example of just how simple REST framework APIs can now be, heres an API written in a single urls.py
module:
"""
A REST framework API for viewing and editing users and groups.
"""
from django.conf.urls.defaults import url, patterns, include
from rest_framework import viewsets, routers
# ViewSets define the view behavior.

model = User
model = Group
# Routers provide an easy way of automatically determining the URL conf

router.register(rusers, UserViewSet)
router.register(rgroups, GroupViewSet)
65

)
The best place to get started with ViewSets and Routers is to take a look at the newest section in the tutorial, which
demonstrates their usage.
7.13.2 Simpler views

This release rationalises the API and implementation of the generic views, dropping the dependency on Djangos
SingleObjectMixin and MultipleObjectMixin classes, removing a number of unneeded attributes, and
generally making the implementation more obvious and easy to work with.
This improvement is reflected in improved documentation for the GenericAPIView base class, and should make it
easier to determine how to override methods on the base class if you need to write customized subclasses.
7.13.3 Easier Serializers

REST framework lets you be totally explicit regarding how you want to represent relationships, allowing you to choose
between styles such as hyperlinking or primary key relationships.
The ability to specify exactly how you want to represent relationships is powerful, but it also introduces complexity.
In order to keep things more simple, REST framework now allows you to include reverse relationships simply by
including the field name in the fields metadata of the serializer class.
For example, in REST framework 2.2, reverse relationships needed to be included explicitly on a serializer class.
class BlogSerializer(serializers.ModelSerializer):
comments = serializers.PrimaryKeyRelatedField(many=True)
class Meta:
model = Blog
fields = (id, title, created, comments)
As of 2.3, you can simply include the field name, and the appropriate serializer field will automatically be used for the
relationship.
class BlogSerializer(serializers.ModelSerializer):
"""
Dont need to specify the comments field explicitly anymore.
"""
class Meta:
model = Blog
fields = (id, title, created, comments)
Similarly, you can now easily include the primary key in hyperlinked relationships, simply by adding the field name
to the metadata.
class BlogSerializer(serializers.HyperlinkedModelSerializer):
"""
This is a hyperlinked serializer, which default to using
a field named url as the primary identifier.
Note that we can now easily also add in the id field.
"""
class Meta:
66
Chapter 7. Topics
model = Blog
fields = (url, id, title, created, comments)
7.13.4 More flexible filtering

The FILTER_BACKEND setting has moved to pending deprecation, in favor of a DEFAULT_FILTER_BACKENDS
setting that takes a list of filter backend classes, instead of a single filter backend class.
The generic view filter_backend attribute has also been moved to pending deprecation in favor of a
filter_backends setting.
Being able to specify multiple filters will allow for more flexible, powerful behavior. New filter classes to handle
searching and ordering of results are planned to be released shortly.
7.14 API Changes

7.14.1 Simplified generic view classes
The functionality provided by SingleObjectAPIView and MultipleObjectAPIView base classes has now
been moved into the base class GenericAPIView. The implementation of this base class is simple enough that
providing subclasses for the base classes of detail and list views is somewhat unnecessary.
Additionally the base generic view no longer inherits from Djangos SingleObjectMixin or
MultipleObjectMixin classes, simplifying the implementation, and meaning you dont need to cross-reference
across to Djangos codebase.
Using the SingleObjectAPIView and MultipleObjectAPIView base classes continues to be supported, but
will raise a PendingDeprecationWarning. You should instead simply use GenericAPIView as the base for
any generic view subclasses.
Removed attributes
The following attributes and methods, were previously present as part of Djangos generic view implementations, but
were unneeded and unused and have now been entirely removed.
context_object_name
get_context_data()
get_context_object_name()
The following attributes and methods, which were previously present as part of Djangos generic view implementations
have also been entirely removed.
paginator_class
get_paginator()
get_allow_empty()
get_slug_field()
7.14. API Changes
67
There may be cases when removing these bits of API might mean you need to write a little more code if your view has
highly customized behavior, but generally we believe that providing a coarser-grained API will make the views easier
to work with, and is the right trade-off to make for the vast majority of cases.
Note that the listed attributes and methods have never been a documented part of the REST framework API, and as
such are not covered by the deprecation policy.
Simplified methods
The get_object and get_paginate_by methods no longer take an optional queryset argument. This makes
overridden these methods more obvious, and a little more simple.
Using an optional queryset with
these
methods
continues
to
be
supported,
but
will
raise
The paginate_queryset method no longer takes a page_size argument, or returns a four-tuple of pagination
information. Instead it simply takes a queryset argument, and either returns a page object with an appropriate page
size, or returns None, if pagination is not configured for the view.
Using the page_size argument is still supported and will trigger the old-style return type, but will raise a
Deprecated attributes
The following attributes are used to control queryset lookup, and have all been moved into a pending deprecation state.
pk_url_kwarg = pk
slug_url_kwarg = slug
slug_field = slug
Their usage is replaced with a single attribute:
lookup_field = pk
This attribute is used both as the regex keyword argument in the URL conf, and as the model field to filter against when
looking up a model instance. To use non-pk based lookup, simply set the lookup_field argument to an alternative
field, and ensure that the keyword argument in the url conf matches the field name.
For example, a view with username based lookup might look like this:
class UserDetail(generics.RetrieveAPIView):
lookup_field = username
And would have the following entry in the urlconf:

url(rûsers/(?P<username>\w+)/$, UserDetail.as_view()),
Usage of the old-style attributes continues to be supported, but will raise a PendingDeprecationWarning.
The allow_empty attribute is also deprecated. To use allow_empty=False style behavior you should explicitly
override get_queryset and raise an Http404 on empty querysets.
For example:
68
Chapter 7. Topics
class DisallowEmptyQuerysetMixin(object):
def get_queryset(self):
queryset = super(DisallowEmptyQuerysetMixin, self).get_queryset()
if not queryset.exists():
raise Http404
return queryset
In our opinion removing lesser-used attributes like allow_empty helps us move towards simpler generic view
implementations, making them more obvious to use and override, and re-enforcing the preferred style of developers
writing their own base classes and mixins for custom behavior rather than relying on the configurability of the generic
views.
7.14.2 Simpler URL lookups

The HyperlinkedRelatedField class now takes a single optional lookup_field argument, that replaces the
pk_url_kwarg, slug_url_kwarg, and slug_field arguments.
For example, you might have a field that references its relationship by a hyperlink based on a slug field:
account = HyperlinkedRelatedField(read_only=True,
lookup_field=slug,
view_name=account-detail)
Usage of the old-style attributes continues to be supported, but will raise a PendingDeprecationWarning.
7.14.3 FileUploadParser
2.3 adds a FileUploadParser parser class, that supports raw file uploads, in addition to the existing multipart
upload support.
7.14.4 DecimalField
2.3 introduces a DecimalField serializer field, which returns Decimal instances.
For most cases APIs using model fields will behave as previously, however if you are using a custom renderer, not
provided by REST framework, then you may now need to add support for rendering Decimal instances to your
renderer implementation.
7.14.5 ModelSerializers and reverse relationships

The support for adding reverse relationships to the fields option on a ModelSerializer class means that the
get_related_field and get_nested_field method signatures have now changed.
In the unlikely event that youre providing a custom serializer class, and implementing these methods you should note
the new call signature for both methods is now (self, model_field, related_model, to_many). For
reverse relationships model_field will be None.
The old-style signature will continue to function but will raise a PendingDeprecationWarning.
7.14. API Changes
69
7.14.6 View names and descriptions

The mechanics of how the names and descriptions used in the browseable API are generated has been modified and
cleaned up somewhat.
If youve been customizing this behavior, for example perhaps to use rst markup for the browseable API, then youll
need to take a look at the implementation to see what updates you need to make.
Note that the relevant methods have always been private APIs, and the docstrings called them out as intended to be
deprecated.
7.15 Other notes

7.15.1 More explicit style
The usage of model attribute in generic Views is still supported, but its usage is generally being discouraged throughout the documentation, in favour of the setting the more explicit queryset and serializer_class attributes.
For example, the following is now the recommended style for using generic views:
class AccountListView(generics.RetrieveAPIView):
queryset = MyModel.objects.all()
serializer_class = MyModelSerializer
Using an explicit queryset and serializer_class attributes makes the functioning of the view more clear
than using the shortcut model attribute.
It also makes the usage of the get_queryset() or get_serializer_class() methods more obvious.
class AccountListView(generics.RetrieveAPIView):
serializer_class = MyModelSerializer
def get_queryset(self):
"""
Determine the queryset dynamically, depending on the
user making the request.
Note that overriding this method follows on more obviously now
that an explicit queryset attribute is the usual view style.
"""
return self.user.accounts
7.15.2 Django 1.3 support

The 2.3.x release series will be the last series to provide compatibility with Django 1.3.
7.15.3 Version 2.2 API changes

All API changes in 2.2 that previously raised PendingDeprecationWarning will now raise a
DeprecationWarning, which is loud by default.
70
Chapter 7. Topics
7.15.4 What comes next?

Support for read-write nested serializers is almost complete, and due to be released in the next few weeks.
Extra filter backends for searching and ordering of results are planned to be added shortly.
The next few months should see a renewed focus on addressing outstanding tickets. The 2.4 release is currently
planned for around August-September.
7.16 Release Notes

Release Early, Release Often
Eric S. Raymond, The Cathedral and the Bazaar.
7.16.1 Versioning
Minor version numbers (0.0.x) are used for changes that are API compatible. You should be able to upgrade between
minor point releases without any other code changes.
Medium version numbers (0.x.0) may include API changes, in line with the deprecation policy. You should read the
release notes carefully before upgrading between medium point releases.
Major version numbers (x.0.0) are reserved for substantial project milestones. No major point releases are currently
planned.
7.16.2 Deprecation policy

REST framework releases follow a formal deprecation policy, which is in line with Djangos deprecation policy.
The timeline for deprecation of a feature present in version 1.0 would work as follows:
Version 1.1 would remain fully backwards compatible with 1.0,
but would raise
PendingDeprecationWarning warnings if you use the feature that are due to be deprecated. These
warnings are silent by default, but can be explicitly enabled when youre ready to start migrating any required
changes. For example if you start running your tests using python -Wd manage.py test, youll be
warned of any API changes you need to make.
Version 1.2 would escalate these warnings to DeprecationWarning, which is loud by default.
Version 1.3 would remove the deprecated bits of API entirely.
Note that in line with Djangos policy, any parts of the framework not mentioned in the documentation should generally
be considered private API, and may be subject to change.
7.16.3 Upgrading
To upgrade Django REST framework to the latest version, use pip:
pip install -U djangorestframework
You can determine your currently installed version using pip freeze:
pip freeze | grep djangorestframework
7.16. Release Notes
71
7.16.4 2.3.x series

2.3.12
Date: 15th January 2014
Security fix: OrderingField now only allows ordering on readable serializer fields, or on fields explicitly
specified using ordering_fields. This prevents users being able to order by fields that are not visible in
the API, and exploiting the ordering of sensitive data such as password hashes.
Bugfix: write_only = True fields now display in the browsable API.
2.3.11
Date: 14th January 2014
Added write_only serializer field argument.
Added write_only_fields option to ModelSerializer classes.
JSON renderer now deals with objects that implement a dict-like interface.
Fix compatiblity with newer versions of django-oauth-plus.
Bugfix: Refine behavior that calls model manager all() across nested serializer relationships, preventing
erronous behavior with some non-ORM objects, and preventing unneccessary queryset re-evaluations.
Bugfix: Allow defaults on BooleanFields to be properly honored when values are not supplied.
Bugfix: Prevent double-escaping of non-latin1 URL query params when appending format=json params.
2.3.10
Date: 6th December 2013
Add in choices information for ChoiceFields in response to OPTIONS requests.
Added pre_delete() and post_delete() method hooks.
Added status code category helper functions.
Bugfix: Partial updates which erronously set a related field to None now correctly fail validation instead of
raising an exception.
Bugfix: Responses without any content no longer include an HTTP Content-Type header.
Bugfix: Correctly handle validation errors in PUT-as-create case, responding with 400.
2.3.9
Date: 15th November 2013
Fix Django 1.6 exception API compatibility issue caused by ValidationError.
Include errors in HTML forms in browsable API.
Added JSON renderer support for numpy scalars.
Added transform_<fieldname> hooks on serializers for easily modifying field output.
Added get_context hook in BrowsableAPIRenderer.
72
Chapter 7. Topics
Allow serializers to be passed files but no data.

HTMLFormRenderer now renders serializers directly to HTML without needing to create an intermediate
form object.
Added get_filter_backends hook.
Added queryset aggregates to allowed fields in OrderingFilter.
Bugfix: Fix decimal suppoprt with YAMLRenderer.
Bugfix: Fix submission of unicode in browsable API through raw data form.
2.3.8
Date: 11th September 2013
Added DjangoObjectPermissions, and DjangoObjectPermissionsFilter.
Support customizable exception handling, using the EXCEPTION_HANDLER setting.
Support customizable view name and description functions, using the VIEW_NAME_FUNCTION and
VIEW_DESCRIPTION_FUNCTION settings.
Added MAX_PAGINATE_BY setting and max_paginate_by generic view attribute.
Added cache attribute to throttles to allow overriding of default cache.
Raw data tab in browsable API now contains pre-populated data.
Raw data and HTML form tab preference in browseable API now saved between page views.
Bugfix: required=True argument fixed for boolean serializer fields.
Bugfix: client.force_authenticate(None) should also clear session info if it exists.
Bugfix: Client sending empty string instead of file now clears FileField.
Bugfix: Empty values on ChoiceFields with required=False now consistently return None.
Bugfix: Clients setting page=0 now simply returns the default page size, instead of disabling pagination. [*]
[*] Note that the change in page=0 behaviour fixes what is considered to be a bug in how clients can effect the
pagination size. However if you were relying on this behavior you will need to add the following mixin to your list
views in order to preserve the existing behavior.
class DisablePaginationMixin(object):
def get_paginate_by(self, queryset=None):
if self.request.QUERY_PARAMS[self.paginate_by_param] == 0:
return None
return super(DisablePaginationMixin, self).get_paginate_by(queryset)
2.3.7
Date: 16th August 2013
Added APITestClient, APIRequestFactory and APITestCase etc...
Refactor SessionAuthentication to allow esier override for CSRF exemption.
7.16. Release Notes
73
Remove Hold down Control message from help_text widget messaging when not appropriate.
Added admin configuration for auth tokens.
Bugfix: AnonRateThrottle fixed to not throttle authenticated users.
Bugfix: Dont set X-Throttle-Wait-Seconds when throttle does not have wait value.
Bugfix: Fixed PATCH button title in browsable API.
Bugfix: Fix issue with OAuth2 provider naive datetimes.
2.3.6
Date: 27th June 2013
Added trailing_slash option to routers.
Include support for HttpStreamingResponse.
Support wider range of default serializer validation when used with custom model fields.
UTF-8 Support for browsable API descriptions.
OAuth2 provider uses timezone aware datetimes when supported.
Bugfix: Return error correctly when OAuth non-existent consumer occurs.
Bugfix: Allow FileUploadParser to correctly filename if provided as URL kwarg.
Bugfix: Fix ScopedRateThrottle.
2.3.5
Date: 3rd June 2013
Added get_url hook to HyperlinkedIdentityField.
Serializer field default argument may be a callable.
@action decorator now accepts a methods argument.
Bugfix: request.user should be still be accessible in renderer context if authentication fails.
Bugfix: The lookup_field option on HyperlinkedIdentityField should apply by default to the url
field on the serializer.
Bugfix:
HyperlinkedIdentityField should continue
slug_url_kwarg, slug_field, in a pending deprecation state.
to
support
pk_url_kwarg,
Bugfix: Ensure we always return 404 instead of 500 if a lookup field cannot be converted to the correct lookup
type. (Eg non-numeric AutoInteger pk lookup)
2.3.4
Date: 24th May 2013
Serializer fields now support label and help_text.
Added UnicodeJSONRenderer.
OPTIONS requests now return metadata about fields for POST and PUT requests.
Bugfix: charset now properly included in Content-Type of responses.
74
Chapter 7. Topics
Bugfix: Blank choice now added in browsable API on nullable relationships.

Bugfix: Many to many relationships with through tables are now read-only.
Bugfix: Serializer fields now respect model field args such as max_length.
Bugfix: SlugField now performs slug validation.
Bugfix: Lazy-translatable strings now properly serialized.
Bugfix: Browsable API now supports bootswatch styles properly.
Bugfix: HyperlinkedIdentityField now uses lookup_field kwarg.
Note: Responses now correctly include an appropriate charset on the Content-Type header. For example:
application/json; charset=utf-8. If you have tests that check the content type of responses, you may
need to update these accordingly.
2.3.3
Date: 16th May 2013
Added SearchFilter
Added OrderingFilter
Added GenericViewSet
Bugfix: Multiple @action and @link methods now allowed on viewsets.
Bugfix: Fix API Root view issue with DjangoModelPermissions
2.3.2
Date: 8th May 2013
Bugfix: Fix TIME_FORMAT, DATETIME_FORMAT and DATE_FORMAT settings.
Bugfix: Fix DjangoFilterBackend issue, failing when used on view with queryset attribute.
2.3.1
Date: 7th May 2013
Bugfix: Fix breadcrumb rendering issue.
2.3.0
Date: 7th May 2013
ViewSets and Routers.
ModelSerializers support reverse relations in fields option.
HyperLinkedModelSerializers support id field in fields option.
Cleaner generic views.
Support for multiple filter classes.
FileUploadParser support for raw file uploads.
7.16. Release Notes
75
DecimalField support.
Made Login template easier to restyle.
Bugfix: Fix issue with depth>1 on ModelSerializer.
Note: See the 2.3 announcement for full details.
7.16.5 2.2.x series

2.2.7
Date: 17th April 2013
Loud failure when view does not return a Response or HttpResponse.
Bugfix: Fix for Django 1.3 compatibility.
Bugfix: Allow overridden get_object() to work correctly.
2.2.6
Date: 4th April 2013
OAuth2 authentication no longer requires unnecessary URL parameters in addition to the token.
URL hyperlinking in browsable API now handles more cases correctly.
Long HTTP headers in browsable API are broken in multiple lines when possible.
Bugfix: Fix regression with DjangoFilterBackend not worthing correctly with single object views.
Bugfix: OAuth should fail hard when invalid token used.
Bugfix: Fix serializer potentially returning None object for models that define __bool__ or __len__.
2.2.5
Date: 26th March 2013
Serializer support for bulk create and bulk update operations.
Regression fix: Date and time fields return date/time objects by default. Fixes regressions caused by 2.2.2. See
#743 for more details.
Bugfix: Fix 500 error is OAuth not attempted with OAuthAuthentication class installed.
Serializer.save() now supports arbitrary keyword args which are passed through to the object .save()
method. Mixins use force_insert and force_update where appropriate, resulting in one less database
query.
2.2.4
OAuth 2 support.
OAuth 1.0a support.
76
Chapter 7. Topics
Support X-HTTP-Method-Override header.

Filtering backends are now applied to the querysets for object lookups as well as lists. (Eg you can use a filtering
backend to control which objects should 404)
Deal with error data nicely when deserializing lists of objects.
Extra override hook to configure DjangoModelPermissions for unauthenticated users.
Bugfix: Fix regression which caused extra database query on paginated list views.
Bugfix: Fix pk relationship bug for some types of 1-to-1 relations.
Bugfix: Workaround for Django bug causing case where Authtoken could be registered for cascade delete
from User even if not installed.
2.2.3
Bugfix: Fix None values for for DateField, DateTimeField and TimeField.
2.2.2
Support for custom input and output formats for DateField, DateTimeField and TimeField.
Cleanup: Request authentication is no longer lazily evaluated, instead authentication is always run, which results
in more consistent, obvious behavior. Eg. Supplying bad auth credentials will now always return an error
response, even if no permissions are set on the view.
Bugfix for serializer data being uncacheable with pickle protocol 0.
Bugfixes for model field validation edge-cases.
Bugfix for authtoken migration while using a custom user model and south.
2.2.1
Date: 22nd Feb 2013
Security fix: Use defusedxml package to address XML parsing vulnerabilities.
Raw data tab added to browsable API. (Eg. Allow for JSON input.)
Added TimeField.
Serializer fields can be mapped to any method that takes no args, or only takes kwargs which have defaults.
Unicode support for view names/descriptions in browsable API.
Bugfix: request.DATA should return an empty QueryDict with no data, not None.
Bugfix: Remove unneeded field validation, which caused extra queries.
Security note: Following the disclosure of security vulnerabilities in Pythons XML parsing libraries, use of the
XMLParser class now requires the defusedxml package to be installed.
The security vulnerabilities only affect APIs which use the XMLParser class, by enabling it in any views, or by
having it set in the DEFAULT_PARSER_CLASSES setting. Note that the XMLParser class is not enabled by default,
so this change should affect a minority of users.
7.16. Release Notes
77
2.2.0
Date: 13th Feb 2013
Python 3 support.
Added a post_save() hook to the generic views.
Allow serializers to handle dicts as well as objects.
Deprecate ManyRelatedField() syntax in favor of RelatedField(many=True)
Deprecate null=True on relations in favor of required=False.
Deprecate blank=True on CharFields, just use required=False.
Deprecate optional obj argument in permissions checks in favor of has_object_permission.
Deprecate implicit hyperlinked relations behavior.
Bugfix: Fix broken DjangoModelPermissions.
Bugfix: Allow serializer output to be cached.
Bugfix: Fix styling on browsable API login.
Bugfix: Fix issue with deserializing empty to-many relations.
Bugfix: Ensure model field validation is still applied for ModelSerializer subclasses with an custom
.restore_object() method.
Note: See the 2.2 announcement for full details.
7.16.6 2.1.x series

2.1.17
Date: 26th Jan 2013
Support proper 401 Unauthorized responses where appropriate, instead of always using 403 Forbidden.
Support json encoding of timedelta objects.
format_suffix_patterns() now supports include style URL patterns.
Bugfix: Fix issues with custom pagination serializers.
Bugfix: Nested serializers now accept source=* argument.
Bugfix: Return proper validation errors when incorrect types supplied for relational fields.
Bugfix: Support nullable FKs with SlugRelatedField.
Bugfix: Dont call custom validation methods if the field has an error.
Note: If the primary authentication class is TokenAuthentication or BasicAuthentication, a view will
now correctly return 401 responses to unauthenticated access, with an appropriate WWW-Authenticate header,
instead of 403 responses.
78
Chapter 7. Topics
2.1.16
Date: 14th Jan 2013
Deprecate django.utils.simplejson in favor of Python 2.6s built-in json module.
Bugfix: auto_now, auto_now_add and other editable=False fields now default to read-only.
Bugfix: PK fields now only default to read-only if they are an AutoField or if editable=False.
Bugfix: Validation errors instead of exceptions when serializers receive incorrect types.
Bugfix: Validation errors instead of exceptions when related fields receive incorrect types.
Bugfix: Handle ObjectDoesNotExist exception when serializing null reverse one-to-one
Note: Prior to 2.1.16, The Decimals would render in JSON using floating point if simplejson was installed, but
otherwise render using string notation. Now that use of simplejson has been deprecated, Decimals will consistently
render using string notation. See #582 for more details.
2.1.15
Date: 3rd Jan 2013
Added PATCH support.
Added RetrieveUpdateAPIView.
Remove unused internal save_m2m flag on ModelSerializer.save().
Tweak behavior of hyperlinked fields with an explicit format suffix.
Relation changes are now persisted in .save() instead of in .restore_object().
Bugfix: Fix issue with FileField raising exception instead of validation error when files=None.
Bugfix: Partial updates should not set default values if field is not included.
2.1.14
Date: 31st Dec 2012
Bugfix: ModelSerializers now include reverse FK fields on creation.
Bugfix: Model fields with blank=True are now required=False by default.
Bugfix: Nested serializers now support nullable relationships.
Note: From 2.1.14 onwards, relational fields move out of the fields.py module and into the new relations.py
module, in order to separate them from regular data type fields, such as CharField and IntegerField.
This change will not affect user code, so long as its following the recommended import style
of from rest_framework import serializers and referring to fields using the style
serializers.PrimaryKeyRelatedField.
2.1.13
Date: 28th Dec 2012
Support configurable STATICFILES_STORAGE storage.
Bugfix: Related fields now respect the required flag, and may be required=False.
7.16. Release Notes
79
2.1.12
Date: 21st Dec 2012
Bugfix: Fix bug that could occur using ChoiceField.
Bugfix: Fix exception in browsable API on DELETE.
Bugfix: Fix issue where pk was was being set to a string if set by URL kwarg.
2.1.11
Date: 17th Dec 2012
Bugfix: Fix issue with M2M fields in browsable API.
2.1.10
Date: 17th Dec 2012
Bugfix: Ensure read-only fields dont have model validation applied.
Bugfix: Fix hyperlinked fields in paginated results.
2.1.9
Date: 11th Dec 2012
Bugfix: Fix broken nested serialization.
Bugfix: Fix Meta.fields only working as tuple not as list.
Bugfix: Edge case if unnecessarily specifying required=False on read only field.
2.1.8
Date: 8th Dec 2012
Fix for creating nullable Foreign Keys with as well as None.
Added null=<bool> related field option.
2.1.7
Date: 7th Dec 2012
Serializers now properly support nullable Foreign Keys.
Serializer validation now includes model field validation, such as uniqueness constraints.
Support true and false string values for BooleanField.
Added pickle support for serialized data.
Support source=dotted.notation style for nested serializers.
Make Request.user settable.
Bugfix: Fix RegexField to work with BrowsableAPIRenderer.
80
Chapter 7. Topics
2.1.6
Date: 23rd Nov 2012
Bugfix: Unfix DjangoModelPermissions. (I am a doofus.)
2.1.5
Date: 23rd Nov 2012
Bugfix: Fix DjangoModelPermissions.
2.1.4
Date: 22nd Nov 2012
Support for partial updates with serializers.
Added RegexField.
Added SerializerMethodField.
Serializer performance improvements.
Added obtain_token_view to get tokens when using TokenAuthentication.
Bugfix: Django 1.5 configurable user support for TokenAuthentication.
2.1.3
Date: 16th Nov 2012
Added FileField and ImageField. For use with MultiPartParser.
Added URLField and SlugField.
Support for read_only_fields on ModelSerializer classes.
Support for clients overriding the pagination page sizes. Use the PAGINATE_BY_PARAM setting or set the
paginate_by_param attribute on a generic view.
201 Responses now return a Location header.
Bugfix: Serializer fields now respect max_length.
2.1.2
Date: 9th Nov 2012
Filtering support.
Bugfix: Support creation of objects with reverse M2M relations.
7.16. Release Notes
81
2.1.1
Date: 7th Nov 2012
Support use of HTML exception templates. Eg. 403.html
Hyperlinked fields take optional slug_field, slug_url_kwarg and pk_url_kwarg arguments.
Bugfix: Deal with optional trailing slashes properly when generating breadcrumbs.
Bugfix: Make textareas same width as other fields in browsable API.
Private API change: .get_serializer now uses same instance and data ordering as serializer initialization.
2.1.0
Date: 5th Nov 2012
Serializer instance and data keyword args have their position swapped.
queryset argument is now optional on writable model fields.
Hyperlinked related fields optionally take slug_field and slug_url_kwarg arguments.
Support Djangos cache framework.
Minor field improvements. (Dont stringify dicts, more robust many-pk fields.)
Bugfix: Support choice field in Browsable API.
Bugfix: Related fields with read_only=True do not require a queryset argument.
API-incompatible changes: Please read this thread regarding the instance and data keyword args before updating to 2.1.0.
7.16.7 2.0.x series

2.0.2
Date: 2nd Nov 2012
Fix issues with pk related fields in the browsable API.
2.0.1
Date: 1st Nov 2012
Add support for relational fields in the browsable API.
Added SlugRelatedField and ManySlugRelatedField.
If PUT creates an instance return 201 Created, instead of 200 OK.
82
Chapter 7. Topics
2.0.0
Date: 30th Oct 2012
Fix all of the things. (Well, almost.)
For more information please see the 2.0 announcement.
7.16.8 0.4.x series

0.4.0
Supports Django 1.5.
Fixes issues with HEAD method.
Allow views to specify template used by TemplateRenderer
More consistent error responses
Some serializer fixes
Fix internet explorer ajax behavior
Minor xml and yaml fixes
Improve setup (e.g. use staticfiles, not the defunct ADMIN_MEDIA_PREFIX)
Sensible absolute URL generation, not using hacky set_script_prefix
7.16.9 0.3.x series

0.3.3
Added DjangoModelPermissions class to support django.contrib.auth style permissions.
Use staticfiles for css files.
Easier to override. Wont conflict with customized admin styles (e.g. grappelli)
Templates are now nicely namespaced.
Allows easier overriding.
Drop implied pk filter if last arg in urlconf is unnamed.
Too magical. Explicit is better than implicit.
Saner template variable auto-escaping.
Tidier setup.py
Updated for URLObject 2.0
Bugfixes:
Bug with PerUserThrottling when user contains unicode chars.
7.16. Release Notes
83
0.3.2
Bugfixes:
Fix 403 for POST and PUT from the UI with UserLoggedInAuthentication (#115)
serialize_model method in serializer.py may cause wrong value (#73)
Fix Error when clicking OPTIONS button (#146)
And many other fixes
Remove short status codes
Zen of Python: There should be one and preferably only one obvious way to do it.
get_name, get_description become methods on the view - makes them overridable.
Improved model mixin API - Hooks for build_query, get_instance_data, get_model, get_queryset, get_ordering
0.3.1
[not documented]
0.3.0
JSONP Support
Bugfixes, including support for latest markdown release
7.16.10 0.2.x series

0.2.4
Fix broken IsAdminUser permission.
OPTIONS support.
XMLParser.
Drop mentions of Blog, BitBucket.
0.2.3
Fix some throttling bugs.
X-Throttle header on throttling.
Support for nesting resources on related models.
0.2.2
Throttling support complete.
84
Chapter 7. Topics
0.2.1
Couple of simple bugfixes over 0.2.0
0.2.0
Big refactoring changes since 0.1.0, ask on the discussion group if anything isnt clear. The public API has been
massively cleaned up. Expect it to be fairly stable from here on in.
Resource becomes decoupled into View and Resource, your views should now inherit from View, not
Resource.
The handler functions on views .get() .put() .post() etc, no longer have the content and auth
args. Use self.CONTENT inside a view to access the deserialized, validated content. Use self.user inside
a view to access the authenticated user.
allowed_methods and anon_allowed_methods are now defunct. if a method is defined, its available.
The permissions attribute on a View is now used to provide generic permissions checking. Use permission classes such as FullAnonAccess, IsAuthenticated or IsUserOrIsAnonReadOnly to set the
permissions.
The authenticators class becomes authentication. Class names change to Authentication.
The emitters class becomes renderers. Class names change to Renderers.
ResponseException becomes ErrorResponse.
The mixin classes have been nicely refactored, the basic mixins are now RequestMixin, ResponseMixin,
AuthMixin, and ResourceMixin You can reuse these mixin classes individually without using the View
class.
7.16.11 0.1.x series

0.1.1
Final build before pulling in all the refactoring changes for 0.2, in case anyone needs to hang on to 0.1.
0.1.0
Initial release.
7.17 Credits
The following people have helped make REST framework great.
Tom Christie - tomchristie
Marko Tibold - markotibold
Paul Miller - paulmillr
Sbastien Piquemal - sebpiq
Carmen Wick - cwick
7.17. Credits
85
Alex Ehlke - aehlke

Alen Mujezinovic - flashingpumpkin
Carles Barrobs - txels
Michael Ftsch - mfoetsch
David Larlet - david
Andrew Straw - astraw
Zeth - zeth
Fernando Zunino - fzunino
Jens Alm - ulmus
Craig Blaszczyk - jakul
Garcia Solero - garciasolero
Tom Drummond - devioustree
Danilo Bargen - dbrgn
Andrew McCloud - amccloud
Thomas Steinacher - thomasst
Meurig Freeman - meurig
Anthony Nemitz - anemitz
Ewoud Kohl van Wijngaarden - ekohl
Michael Ding - yandy
Mjumbe Poe - mjumbewu
Natim - natim
Sebastian Zurek
- sebzur
Benoit C - dzen
Chris Pickett - bunchesofdonald
Ben Timby - btimby
Michele Lazzeri - michelelazzeri-nextage
Camille Harang - mammique
Paul Oswald - poswald
Sean C. Farley - scfarley
Daniel Izquierdo - izquierdo
Can Yavuz - tschan
Shawn Lewis - shawnlewis
Alec Perkins - alecperkins
Michael Barrett - phobologic
Mathieu Dhondt - laundromat
Johan Charpentier - cyberj
86
Chapter 7. Topics
Jamie Matthews - j4mie

Mattbo - mattbo
Max Hurl - maximilianhurl
Tomi Pajunen - eofs
Rob Dobson - rdobson
Daniel Vaca Araujo - diviei
Madis Vin - madisvain
Stephan Gro - minddust
Pavel Savchenko - asfaltboy
Otto Yiu - ottoyiu
Jacob Magnusson - jmagnusson
Osiloke Harold Emoekpere - osiloke
Michael Shepanski - mjs7231
Toni Michel - tonimichel
Ben Konrath - benkonrath
Marc Aymerich - glic3rinu
Ludwig Kraatz - ludwigkraatz
Rob Romano - robromano
Eugene Mechanism - mechanism
Jonas Liljestrand - jonlil
Justin Davis - irrelative
Dustin Bachrach - dbachrach
Mark Shirley - maspwr
Olivier Aubert - oaubert
Yuri Prezument - yprez
Fabian Buechler - fabianbuechler
Mark Hughes - mhsparks
Michael van de Waeter - mvdwaeter
Reinout van Rees - reinout
Michael Richards - justanotherbody
Ben Roberts - roberts81
Venkata Subramanian Mahalingam - annacoder
George Kappel - gkappel
Colin Murtaugh - cmurtaugh
Simon Pantzare - pilt
Szymon Tez ewski - sunscrapers
7.17. Credits
87
Joel Marcotte - joual

Trey Hunner - treyhunner
Roman Akinfold - akinfold
Toran Billups - toranb
Sbastien Bal - sebastibe
Andrew Hankinson - ahankinson
Juan Riaza - juanriaza
Michael Mior - michaelmior
Marc Tamlyn - mjtamlyn
Richard Wackerbarth - wackerbarth
Johannes Spielmann - shezi
James Cleveland - radiosilence
Steve Gregory - steve-gregory
Federico Capoano - nemesisdesign
Bruno Reni - brutasse
Kevin Stone - kevinastone
Guglielmo Celata - guglielmo
Mike Tums - mktums
Michael Elovskikh - wronglink
Micha Jaworski - swistakm
Andrea de Marco - z4r
Fernando Rocha - fernandogrd
Xavier Ordoquy - xordoquy
Adam Wentz - floppya
Andreas Pelme - pelme
Ryan Detzel - ryanrdetzel
Omer Katz - thedrow
Wiliam Souza - waa
Jonas Braun - iekadou
Ian Dash - bitmonkey
Bouke Haarsma - bouke
Pierre Dulac - dulaccc
Dave Kuhn - kuhnza
Sitong Peng - stoneg
Victor Shih - vshih
Atle Frenvik Sveen - atlefren
88
Chapter 7. Topics
J Paul Reed - preed

Matt Majewski - forgingdestiny
Jerome Chen - chenjyw
Andrew Hughes - eyepulp
Daniel Hepper - dhepper
Hamish Campbell - hamishcampbell
Marlon Bailey - avinash240
James Summerfield - jsummerfield
Andy Freeland - rouge8
Craig de Stigter - craigds
Pablo Recio - pyriku
Brian Zambrano - brianz
scar Vilaplana - grimborg
Ryan Kaskel - ryankask
Andy McKay - andymckay
Matteo Suppo - matteosuppo
Karol Majta - lolek09
David Jones - commonorgarden
Andrew Tarzwell - atarzwell
Michal Dvork - mikee2185
Markus Trnqvist - mjtorn
Pascal Borreli - pborreli
Alex Burgel - aburgel
David Medina - copitux
Areski Belaid - areski
Ethan Freman - mindlace
David Sanders - davesque
Philip Douglas - freakydug
Igor Kalat - trwired
Rudolf Olah - omouse
Gertjan Oude Lohuis - gertjanol
Matthias Jacob - cyroxx
Pavel Zinovkin - pzinovkin
Will Kahn-Greene - willkg
Kevin Brown - kevin-brown
Rodrigo Martell - coderigo
7.17. Credits
89
James Rutherford - jimr

Ricky Rosario - rlr
Veronica Lynn - kolvia
Dan Stephenson - etos
Martin Clement - martync
Jeremy Satterfield - jsatt
Christopher Paolini - chrispaolini
Filipe A Ximenes - filipeximenes
Ramiro Morales - ramiro
Krzysztof Jurewicz - krzysiekj
Eric Buehl - ericbuehl
Kristian llegaard - kristianoellegaard
Alexander Akhmetov - alexander-akhmetov
Andrey Antukh - niwibe
Mathieu Pillard - diox
Edmond Wong - edmondwong
Ben Reilly - bwreilly
Tai Lee - mrmachine
Markus Kaiserswerth - mkai
Henry Clifford - hcliff
Thomas Badaud - badale
Colin Huang - tamakisquare
Ross McFarland - ross
Jacek Bzdak - jbzdak
Alexander Lukanin - alexanderlukanin13
Yamila Moreno - yamila-moreno
Rob Hudson - robhudson
Alex Good - alexjg
Ian Foote - ian-foote
Chuck Harmston - chuckharmston
Philip Forget - philipforget
Artem Mezhenin - amezhenin
Many thanks to everyone whos contributed to the project.
90
Chapter 7. Topics
7.17.1 Additional thanks

The documentation is built with Bootstrap and Markdown.
Project hosting is with GitHub.
Continuous integration testing is managed with Travis CI.
The live sandbox is hosted on Heroku.
Various inspiration taken from the Rails, Piston, Tastypie, Dagny and django-viewsets projects.
Development of REST framework 2.0 was sponsored by DabApps.
7.17.2 Contact
For usage questions please see the REST framework discussion group.
You can also contact @_tomchristie directly on twitter.
7.17. Credits
91
92
Chapter 7. Topics
CHAPTER 8
Indices and tables
genindex
modindex
search
93
94
Chapter 8. Indices and tables
CHAPTER 9
Development
If you want to work on REST framework itself, clone the repository, then...
Run the tests:
./rest_framework/runtests/runtests.py
To run the tests against all supported configurations, first install the tox testing tool globally, using pip install
tox, then simply run tox:
tox
95
96
Chapter 9. Development
CHAPTER 10
Support
For support please see the REST framework discussion group, try the #restframework channel on
irc.freenode.net, search the IRC archives, or raise a question on Stack Overflow, making sure to include
the django-rest-framework tag.
Paid support is available from DabApps, and can include work on REST framework core, or support with building
your REST framework API. Please contact DabApps if youd like to discuss commercial support options.
For updates on REST framework development, you may also want to follow the author on Twitter.
Follow @_tomchristie
97
98
Chapter 10. Support
CHAPTER 11
Security
If you believe youve found something in Django REST framework which has security implications, please do not
raise the issue in a public forum.
Send a description of the issue via email to rest-framework-security@googlegroups.com. The project maintainers will
then work with you to resolve any issues where required, prior to any public disclosure.
99
100
Chapter 11. Security
CHAPTER 12
License
Copyright (c) 2011-2014, Tom Christie All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS AS IS AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
101

Django Rest Framework

Uploaded by

Django Rest Framework

Uploaded by

Django Rest Framework

December 06, 2014

Indices and tables

Django Rest Framework Documentation, Release 2.3

Django Rest Framework Documentation, Release 2.3

Figure 1: Screenshot from the browsable API

REST framework requires the following:

Django Rest Framework Documentation, Release 2.3

Install using pip, including any optional packages you want...

...or clone the project from github.

Add rest_framework to your INSTALLED_APPS setting.

Django Rest Framework Documentation, Release 2.3

# Routers provide an easy way of automatically determining the URL conf.

# Wire up our API using automatic URL routing.

Django Rest Framework Documentation, Release 2.3

Django Rest Framework Documentation, Release 2.3

5.1.1 Project setup

Django Rest Framework Documentation, Release 2.3

The run syncdb like so:

Django Rest Framework Documentation, Release 2.3

Okay, were done.

Django Rest Framework Documentation, Release 2.3

5.1.6 Testing our API

Or directly through the browser...

5.2 Tutorial 1: Serialization

Django Rest Framework Documentation, Release 2.3

Figure 5.1: Quick start image

5.2. Tutorial 1: Serialization

Django Rest Framework Documentation, Release 2.3

5.2.2 Setting up a new environment

5.2.3 Getting started

Okay, were ready to roll.

Django Rest Framework Documentation, Release 2.3

5.2.4 Creating a model to work with

Dont forget to sync the database for the first time.

5.2.5 Creating a Serializer class

5.2. Tutorial 1: Serialization

Django Rest Framework Documentation, Release 2.3

def restore_object(self, attrs, instance=None):

5.2.6 Working with Serializers

snippets.models import Snippet

snippet = Snippet(code=foo = "bar"\n)

Django Rest Framework Documentation, Release 2.3

Deserialization is similar. First we parse a stream into Python native datatypes...

serializer = SnippetSerializer(Snippet.objects.all(), many=True)

5.2.7 Using ModelSerializers

5.2.8 Writing regular Django views using our Serializer

5.2. Tutorial 1: Serialization

Django Rest Framework Documentation, Release 2.3

django.http import HttpResponse

Django Rest Framework Documentation, Release 2.3

serializer = SnippetSerializer(snippet, data=data)

5.2.9 Testing our first attempt at a Web API

...and start up Djangos development server.

In another terminal window, we can test the server.

Or we can get a particular snippet by referencing its id.

5.2. Tutorial 1: Serialization

Django Rest Framework Documentation, Release 2.3

5.2.10 Where are we now

5.3 Tutorial 2: Requests and Responses

5.3.1 Request objects

# Only handles form data.

Only works for POST method.

5.3.2 Response objects

# Renders to content type as requested by the client.

5.3.3 Status codes

5.3.4 Wrapping API views

Django Rest Framework Documentation, Release 2.3

5.3.5 Pulling it all together

rest_framework import status

5.3. Tutorial 2: Requests and Responses

Django Rest Framework Documentation, Release 2.3

5.3.6 Adding optional format suffixes to our URLs

5.3.7 Hows it looking?

Or by appending a format suffix:

Django Rest Framework Documentation, Release 2.3