<divclass="clear"><inputclass="btn btn-success"type="submit"value="Yes, keep me posted!"name="subscribe"id="mc-embedded-subscribe"class="button"></div>
</form>
</div>
</style></div>
</ul>
<!--End mc_embed_signup-->
</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>
<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>
<h2id="urls">URLs</h2>
<p>Okay, now let's wire up the API URLs. On to <code>tutorial/urls.py</code>...</p>
<preclass="prettyprint lang-py"><code>from django.conf.urls import patterns, url, include
from rest_framework import routers
from 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 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>
