<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>
<preclass="prettyprint lang-py"><code># 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
pip install djangorestframework
# Create a new app
python manage.py startapp quickstart
</code></pre>
<p>Next you'll need to get a database set up and synced. If you just want to use SQLite for now, then you'll want to edit your <code>tutorial/settings.py</code> module to include something like this:</p>
<p>Once you've set up a database and got everything synced 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 in <code>quickstart/serializers.py</code> that we'll use for our data representations.</p>
<preclass="prettyprint lang-py"><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>quickstart/views.py</code> and get typing.</p>
<preclass="prettyprint lang-py"><code>from django.contrib.auth.models import User, Group
from rest_framework import viewsets
from 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>
<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 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>
