<ulclass="nav nav-list side-nav well sidebar-nav-fixed">
<liclass="main">
<ahref="#quickstart">Quickstart</a>
</li>
<li>
<ahref="#project-setup">Project setup</a>
</li>
<li>
<ahref="#serializers">Serializers</a>
</li>
<li>
<ahref="#views">Views</a>
</li>
<li>
<ahref="#urls">URLs</a>
</li>
<li>
<ahref="#settings">Settings</a>
</li>
<li>
<ahref="#testing-our-api">Testing our API</a>
</li>
</ul>
</div>
</div>
<divid="main-content"class="span9">
<h1id="quickstart">Quickstart</h1>
<p>We're going to create a simple API to allow admin users to view and edit the users and groups in the system.</p>
<h2id="project-setup">Project setup</h2>
<p>Create a new Django project named <code>tutorial</code>, then start a new app called <code>quickstart</code>.</p>
<pre><code># Create the project directory
mkdir 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
pip install djangorestframework
# Set up a new project with a single application
django-admin.py startproject tutorial
cd tutorial
django-admin.py startapp quickstart
cd ..
</code></pre>
<p>Now sync your database for the first time:</p>
<pre><code>python manage.py migrate
</code></pre>
<p>We'll also create an initial user named <code>admin</code> with a password of <code>password</code>. We'll authenticate as that user later in our example.</p>
<pre><code>python manage.py createsuperuser
</code></pre>
<p>Once you've set up a database and initial user created and ready to go, open up the app's directory and we'll get coding...</p>
<h2id="serializers">Serializers</h2>
<p>First up we're going to define some serializers. Let's create a new module named <code>tutorial/quickstart/serializers.py</code> that we'll use for our data representations.</p>
<pre><code>from django.contrib.auth.models import User, Group
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')
</code></pre>
<p>Notice that we're using hyperlinked relations in this case, with <code>HyperlinkedModelSerializer</code>. You can also use primary key and various other relationships, but hyperlinking is good RESTful design.</p>
<h2id="views">Views</h2>
<p>Right, we'd better write some views then. Open <code>tutorial/quickstart/views.py</code> and get typing.</p>
<pre><code>from django.contrib.auth.models import User, Group
from rest_framework import viewsets
from tutorial.quickstart.serializers import UserSerializer, GroupSerializer
class UserViewSet(viewsets.ModelViewSet):
"""
API endpoint that allows users to be viewed or edited.
"""
queryset = User.objects.all()
serializer_class = UserSerializer
class GroupViewSet(viewsets.ModelViewSet):
"""
API endpoint that allows groups to be viewed or edited.
"""
queryset = Group.objects.all()
serializer_class = GroupSerializer
</code></pre>
<p>Rather than write multiple views we're grouping together all the common behavior into classes called <code>ViewSets</code>.</p>
<p>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.</p>
<p>Notice that our viewset classes here are a little different from those in the <ahref="../../../#example">frontpage example</a>, as they include <code>queryset</code> and <code>serializer_class</code> attributes, instead of a <code>model</code> attribute.</p>
<p>For trivial cases you can simply set a <code>model</code> attribute on the <code>ViewSet</code> class and the serializer and queryset will be automatically generated for you. Setting the <code>queryset</code> and/or <code>serializer_class</code> attributes gives you more explicit control of the API behaviour, and is the recommended style for most applications.</p>
<h2id="urls">URLs</h2>
<p>Okay, now let's wire up the API URLs. On to <code>tutorial/urls.py</code>...</p>
<pre><code>from django.conf.urls import url, include
from rest_framework import routers
from tutorial.quickstart import views
router = routers.DefaultRouter()
router.register(r'users', views.UserViewSet)
router.register(r'groups', views.GroupViewSet)
# Wire up our API using automatic URL routing.
# Additionally, we include login URLs for the browseable API.
<p>Because we're using viewsets instead of views, we can automatically generate the URL conf for our API, by simply registering the viewsets with a router class.</p>
<p>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.</p>
<p>Finally, we're including default login and logout views for use with the browsable API. That's optional, but useful if your API requires authentication and you want to use the browsable API.</p>
<h2id="settings">Settings</h2>
<p>We'd also like to set a few global settings. We'd like to turn on pagination, and we want our API to only be accessible to admin users. The settings module will be in <code>tutorial/settings.py</code></p>
<p>If you're working through the browser, make sure to login using the control in the top right corner.</p>
<p>Great, that was easy!</p>
<p>If you want to get a more in depth understanding of how REST framework fits together head on over to <ahref="../1-serialization">the tutorial</a>, or start browsing the <ahref="../../../#api-guide">API guide</a>.</p>
