<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>
<p>Create a new Django project, and start a new app called <code>quickstart</code>. 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', 'permissions')
</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>
<preclass="prettyprint lang-py"><code>from django.contrib.auth.models import User, Group
from rest_framework import generics
from rest_framework.decorators import api_view
from rest_framework.reverse import reverse
from rest_framework.response import Response
from quickstart.serializers import UserSerializer, GroupSerializer
@api_view(['GET'])
def api_root(request, format=None):
"""
The entry endpoint of our API.
"""
return Response({
'users': reverse('user-list', request=request),
'groups': reverse('group-list', request=request),
})
class UserList(generics.ListCreateAPIView):
"""
API endpoint that represents a list of users.
"""
model = User
serializer_class = UserSerializer
class UserDetail(generics.RetrieveUpdateDestroyAPIView):
"""
API endpoint that represents a single user.
"""
model = User
serializer_class = UserSerializer
class GroupList(generics.ListCreateAPIView):
"""
API endpoint that represents a list of groups.
"""
model = Group
serializer_class = GroupSerializer
class GroupDetail(generics.RetrieveUpdateDestroyAPIView):
"""
API endpoint that represents a single group.
"""
model = Group
serializer_class = GroupSerializer
</code></pre>
<p>Let's take a moment to look at what we've done here before we move on. We have one function-based view representing the root of the API, and four class-based views which map to our database models, and specify which serializers should be used for representing that data. Pretty simple stuff.</p>
<h2id="urls">URLs</h2>
<p>Okay, let's wire this baby up. On to <code>quickstart/urls.py</code>...</p>
<preclass="prettyprint lang-py"><code>from django.conf.urls import patterns, url, include
from rest_framework.urlpatterns import format_suffix_patterns
from quickstart.views import UserList, UserDetail, GroupList, GroupDetail
<p>Firstly the names <code>user-detail</code> and <code>group-detail</code> are important. We're using the default hyperlinked relationships without explicitly specifying the view names, so we need to use names of the style <code>{modelname}-detail</code> to represent the model instance views.</p>
<p>Secondly, we're modifying the urlpatterns using <code>format_suffix_patterns</code>, to append optional <code>.json</code> style suffixes to our URLs.</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 browseable 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.</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>
