Building APIs with Django and Django

Rest Framework
Release 2.0

Agiliq

Mar 15, 2018

 Contents

1 Setup, Models and Admin 3

1.1 Creating a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Database setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 Creating models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 Activating models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 A simple API with pure Django 7

2.1 The endpoints and the URLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Connecting urls to the views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.3 Writing the views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.4 Using the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.5 Why do we need DRF? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3 Serialiering and Deserializing Data 11

3.1 Serialization and Deserialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 Creating Serializers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3 The PollSerializer in detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.4 Using the PollSerializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4 Views and Generic Views 15

4.1 Creating Views with APIView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2 Using DRF generic views to simplify code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.3 More generic views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.4 Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5 More views and viewsets 23

5.1 A better URL structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.2 Changing the views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.3 Introducing Viewsets and Routers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.4 Choosing the base class to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.5 Next steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6 Access Control 27
6.1 Creating a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.2 Authentication scheme setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.3 The login API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.4 Fine grained access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

i
 6.5 Next steps: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7 Testing and Continuous Integeration 33

7.1 Creating Test Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
7.2 Testing authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
7.3 Continuous integration with CircleCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
7.4 Writing circle.yml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

8 Appendix 39
8.1 Testing and using api with Postman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
8.2 Documenting APIs with Swagger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
8.3 Documenting API with RAML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

ii
 Building APIs with Django and Django Rest Framework, Release 2.0

Building APIs with Django and DRF takes over where the Django tutorials stop. In the Django tutorials, you built a
regular Django polls app. We will rebuild an API for a similar app.
In the chapters to come, we will build a REST(ish) api with authorization, rate limiting, first with pure Django and
then with DRF. We will cover testing, contious integration, documentation tools and API collaboration tools.

Chapters:

Contents 1
Building APIs with Django and Django Rest Framework, Release 2.0

2 Contents
 CHAPTER 1

Setup, Models and Admin

In this tutorial we will walk through a process of creating an API for a basic poll application. We will be using Python
3.6.x, Django 2.0.x and Django Rest Framework 3.7.x for creating API.
First things first, let’s install the required modules within a virtual environment.
mkvirtualenv pollsapi
pip install Django
pip install djangorestframework

1.1 Creating a project

Earliest in order, to create a project we should move to the directory where we would like to store our code. For this
go to command line and use cd command. Then trigger the startproject command.
django-admin startproject pollsapi

This command gives us a ‘pollsapi’ directoy. The contents of this directory look like this:
manage.py

pollsapi/
__init__.py
settings.py
urls.py
wsgi.py

1.2 Database setup

We will use SQlite database, which is already included with Python. The pollsapi/settings.py file woul
already have the correct settings.

3
Building APIs with Django and Django Rest Framework, Release 2.0

DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
}
}

Now, use the migrate command which builds the needed database tables in regard to the django_pollsapi/
settings.py file.

python manage.py migrate

1.3 Creating models

Before creating our database models, let us create our pollsapi App.

python manage.py startapp polls

The above command results in a ‘polls’ directory containing different files:

admin.py
apps.py
models.py
tests.py
views.py

Step in to ‘models.py’ file and start writing the models. For creating the polls api we are going to create a Poll
model, a Choice model and a Vote model. Once we are done with designing our models, the :code:’models.py’ file
should look like this:
These models are the same as you would have seen in the Django introduction tutorial.

from django.db import models

from django.contrib.auth.models import User

class Poll(models.Model):
question = models.CharField(max_length=100)
created_by = models.ForeignKey(User, on_delete=models.CASCADE)
pub_date = models.DateTimeField(auto_now=True)

def __str__(self):
return self.question

class Choice(models.Model):
poll = models.ForeignKey(Poll, related_name='choices',on_delete=models.CASCADE)
choice_text = models.CharField(max_length=100)

def __str__(self):
return self.choice_text

class Vote(models.Model):
choice = models.ForeignKey(Choice, related_name='votes', on_delete=models.CASCADE)

4 Chapter 1. Setup, Models and Admin

 Building APIs with Django and Django Rest Framework, Release 2.0

poll = models.ForeignKey(Poll, on_delete=models.CASCADE)

voted_by = models.ForeignKey(User, on_delete=models.CASCADE)

class Meta:
unique_together = ("poll", "voted_by")

The above models have been designed in such a way that, it would make our API bulding a smooth process.

1.4 Activating models

With the simple lines of code in the ‘models.py’ Django can create a database schema and a Python database-access
API which has the capablity to access the objects of Poll, Choice, Vote. To create the database tables to our models,
‘rest_framework’ and ‘pollsapi’ app needs to be added to the “INSTALLED_APPS” in the ‘django_pollsapi/settings’
file.

INSTALLED_APPS = (
...
'rest_framework',
'polls',
)

Now, run the makemigrations command which will notify Django that new models have been created and those
changes needs to be applied to the migration. Run migrate command to do the actual migration.

$ python manage.py makemigrations polls

$ python manage.py migrate

Create an empty urls.py in your polls app.

urlpatterns = [
]

Go to pollsapi/urls.py and include the polls urls.

urlpatterns = [
re_path(r'^', include('polls.urls')),
]

Now you can runserver

$ python manage.py runserver

Goto any browser of your choice and hit the url http://127.0.0.1:8000
And we are in business, with a Django Congratulations page greeting us. (Though we haven’t added any API endpoints
yet.)

1.4. Activating models 5

Building APIs with Django and Django Rest Framework, Release 2.0

We will be adding API endpoints for creating and viewing polls in the next chapter.

1.4.1 Setting up the admin

You should register Poll and Choice in the admin like this.

from django.contrib import admin

from .models import Poll, Choice

admin.site.register(Poll)
admin.site.register(Choice)

6 Chapter 1. Setup, Models and Admin

 CHAPTER 2

A simple API with pure Django

In this chapter, we will build an API with pure Django. We will not use Django Rest Framework (Or any other library).
To start add some Poll using the admin.

2.1 The endpoints and the URLS

Our API will have two endpoints returning data in JSON format.
• /polls/ GETs list of Poll
• /polls/<id>/ GETs data of a specific Poll

2.2 Connecting urls to the views

Write two place holder view functions and connect them in your urls.py. We will finish polls_list and
polls_detail shortly.

# In views.py
def polls_list(request):
pass

def polls_detail(request, pk):

pass

# in urls.py
from django.urls import path
from .views import polls_list, polls_detail

urlpatterns = [
path("polls/", polls_list, name="polls_list"),

7
Building APIs with Django and Django Rest Framework, Release 2.0

path("polls/<int:pk>/", polls_detail, name="polls_detail")

]

2.3 Writing the views

We will now write the polls_list and polls_detail

from django.shortcuts import render, get_object_or_404

from django.http import JsonResponse

from .models import Poll

def polls_list(request):
MAX_OBJECTS = 20
polls = Poll.objects.all()[:20]
data = {"results": list(polls.values("question", "created_by__username", "pub_date
˓→"))}

return JsonResponse(data)

def polls_detail(request, pk):

poll = get_object_or_404(Poll, pk=pk)
data = {"results": {
"question": poll.question,
"created_by": poll.created_by.username,
"pub_date": poll.pub_date
}}
return JsonResponse(data)

This should be standard Django for you. polls = Poll.objects.all()[:20] gets us upto 20
Poll objects. We get a list of dictionaries using {"results": list(polls.values("question",
"created_by__username", "pub_date"))} and return it with a JsonResponse. A JsonResponse is
a like HttpResponse with content-type=application/json.
Similarly, polls_detail gets a specific Poll using get_object_or_404(Poll, pk=pk), and returns it wrapped
in JsonResponse.

2.4 Using the API

You can now access the API using curl, wget, postman, browser or any other API consuming tools. Here us the
response with curl.

$ curl http://localhost:8000/polls/

{"results": [{"pk": 1, "question": "What is the weight of an unladen swallow?",

˓→"created_by__username": "shabda", "pub_date": "2018-03-12T10:14:19.002Z"}, {"pk": 2,

˓→ "question": "What do you prefer, Flask or Django?", "created_by__username": "shabda

˓→", "pub_date": "2018-03-12T10:15:55.949Z"}, {"pk": 3, "question": "What is your

˓→favorite vacation spot?", "created_by__username": "shabda", "pub_date": "2018-03-

˓→12T10:16:11.998Z"}]}

You should consider using postman or a similar tool. This is how your API looks in Postman.

8 Chapter 2. A simple API with pure Django

 Building APIs with Django and Django Rest Framework, Release 2.0

2.5 Why do we need DRF?

(DRF = Django Rest Framework)

We were able to build the API with just Django, without using DRF, so why do we need DRF? Almost always, you
will need common tasks with your APIs, such as access control, serailization, rate limiting and more.
DRF provides a well thought out set of base components and convenient hook points for building APIs. We will be
using DRF in the rest of the chapters.

2.5. Why do we need DRF? 9

Building APIs with Django and Django Rest Framework, Release 2.0

10 Chapter 2. A simple API with pure Django

 CHAPTER 3

Serialiering and Deserializing Data

DRF makes the process of building web API’s simple and flexible. With batteries included, it comes with well designed
base classes to allows to serialize and deserialize data.

3.1 Serialization and Deserialization

The first thing we need for our API is to provide a way to serialize model instances into representations. Serialization is
the process of making a streamable representation of the data which we can transfer over the network. Deserialization
is its reverse process.

3.2 Creating Serializers

Lets get started with creating serializer classes which will serialize and deserialize the model instances to json repre-
sentations. Create a file named polls/serializers.py. We will use ModelSerializer which will reduce
code duplication by automatically determing the set of fields and by creating implementations of the create() and
update() methods.
Our polls/serializers.py looks like this.

from rest_framework import serializers

from .models import Poll, Choice, Vote

class VoteSerializer(serializers.ModelSerializer):
class Meta:
model = Vote
fields = '__all__'

class ChoiceSerializer(serializers.ModelSerializer):

11
Building APIs with Django and Django Rest Framework, Release 2.0

votes = VoteSerializer(many=True, required=False)

class Meta:
model = Choice
fields = '__all__'

class PollSerializer(serializers.ModelSerializer):
choices = ChoiceSerializer(many=True, read_only=True, required=False)

class Meta:
model = Poll
fields = '__all__'

3.3 The PollSerializer in detail

Our PollSerializer looks like this.

...

class PollSerializer(serializers.ModelSerializer):
choices = ChoiceSerializer(many=True, read_only=True, required=False)

class Meta:
model = Poll
fields = '__all__'

What have we got with this? The PollSerializer class has a number of methods,
• A is_valid(self, ..) method which can tell if the data is sufficient and valid to create/update a model
instance.
• A save(self, ..) method, which khows how to create or update an instance.
• A create(self, validated_data, ..) method which knows how to create an instance. This method
can be overriden to customize the create behaviour.
• A update(self, instance, validated_data, ..) method which knows how to update an in-
stance. This method can be overriden to customize the update behaviour.

3.4 Using the PollSerializer

Let’s use the serializer to create a Poll object.

In [1]: from polls.serializers import PollSerializer

In [2]: from polls.models import Poll

In [3]: poll_serializer = PollSerializer(data={"question": "Mojito or Caipirinha?",

˓→"created_by": 1})

In [4]: poll_serializer.is_valid()
Out[4]: True

12 Chapter 3. Serialiering and Deserializing Data

 Building APIs with Django and Django Rest Framework, Release 2.0

In [5]: poll = poll_serializer.save()

In [6]: poll.pk
Out[6]: 5

The poll.pk line tells us that the object has been commited to the DB. You can also use the serializer to update a
Poll object.

In [9]: poll_serializer = PollSerializer(instance=poll, data={"question": "Mojito,

˓→Caipirinha or margarita?", "created_by": 1})

In [10]: poll_serializer.is_valid()
Out[10]: True

In [11]: poll_serializer.save()
Out[11]: <Poll: Mojito, Caipirinha or margarita?>

In [12]: Poll.objects.get(pk=5).question
Out[12]: 'Mojito, Caipirinha or margarita?'

We can see that calling save on a Serializer with instance causes that instance to be updated. Poll.objects.
get(pk=5).question verifies that the Poll was updated.
In the next chapter, we will use the serializers to write views.

3.4. Using the PollSerializer 13

Building APIs with Django and Django Rest Framework, Release 2.0

14 Chapter 3. Serialiering and Deserializing Data

 CHAPTER 4

Views and Generic Views

In this chapter, we will create views using APIVIew, and generics.ListCreateAPIView and family.

4.1 Creating Views with APIView

To start with, we will use the APIView to build the polls list and poll detail API we built in the chapter, A simple API
with pure Django.
Add this to a new file polls/apiviews.py

from rest_framework.views import APIView

from rest_framework.response import Response
from django.shortcuts import get_object_or_404

from .models import Poll, Choice

from .serializers import PollSerializer

class PollList(APIView):
def get(self, request):
polls = Poll.objects.all()[:20]
data = PollSerializer(polls, many=True).data
return Response(data)

class PollDetail(APIView):
def get(self, request, pk):
poll = get_object_or_404(Poll, pk=pk)
data = PollSerializer(poll).data
return Response(data)

And change your urls.py to

from django.urls import path

15
Building APIs with Django and Django Rest Framework, Release 2.0

from .apiviews import PollList, PollDetail

urlpatterns = [
path("polls/", PollList.as_view(), name="polls_list"),
path("polls/<int:pk>/", PollDetail.as_view(), name="polls_detail")
]

DRF comes with a browsable api, so you can directly open http://localhost:8000/polls/ in the browser.
It looks like this

You can now do an options request to /polls/, which gives

{
"name": "Poll List",
"description": "",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
]
}

This is how it looks like in postman.

16 Chapter 4. Views and Generic Views

 Building APIs with Django and Django Rest Framework, Release 2.0

4.2 Using DRF generic views to simplify code

The PollList and PollDetail get the work done, but there are bunch of common operations, we can do it in
abstract away.
The generic views of Django Rest Framework help us in code reusablity. They infer the response format and allowed
methods from the serilizer class and base class.
Change your apiviews.py to the below code, and leave urls.py as is.

from rest_framework import generics

from .models import Poll, Choice

from .serializers import PollSerializer, ChoiceSerializer,\
VoteSerializer

class PollList(generics.ListCreateAPIView):
queryset = Poll.objects.all()
serializer_class = PollSerializer

class PollDetail(generics.RetrieveDestroyAPIView):
queryset = Poll.objects.all()
serializer_class = PollSerializer

With this change, GET requests to /polls/ and /polls/<pk>/, continue to work as was, but we have a more
data available with OPTIONS.
Do an OPTIONs request to /polls/, and you will get a response like this.

{
"name": "Poll List",

4.2. Using DRF generic views to simplify code 17

Building APIs with Django and Django Rest Framework, Release 2.0

"description": "",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
],
"actions": {
"POST": {
"id": {
"type": "integer",
"required": false,
"read_only": true,
"label": "ID"
},
// ...
},
"question": {
"type": "string",
"required": true,
"read_only": false,
"label": "Question",
"max_length": 100
},
"pub_date": {
"type": "datetime",
"required": false,
"read_only": true,
"label": "Pub date"
},
"created_by": {
"type": "field",
"required": true,
"read_only": false,
"label": "Created by"
}
}
}
}

This tells us
• Our API now accepts POST
• The required data fields
• The type of each data field.
Pretty nifty! This is what it looks like in Postman.

18 Chapter 4. Views and Generic Views

 Building APIs with Django and Django Rest Framework, Release 2.0

4.3 More generic views

Let us add the view to create choices and for voting. We will look more closely at this code shortly.
from rest_framework import generics

from .models import Poll, Choice

from .serializers import PollSerializer, ChoiceSerializer, VoteSerializer

class PollList(generics.ListCreateAPIView):
queryset = Poll.objects.all()
serializer_class = PollSerializer

class PollDetail(generics.RetrieveDestroyAPIView):
queryset = Poll.objects.all()
serializer_class = PollSerializer

4.3. More generic views 19

Building APIs with Django and Django Rest Framework, Release 2.0

class ChoiceList(generics.ListCreateAPIView):
queryset = Choice.objects.all()
serializer_class = ChoiceSerializer

class CreateVote(generics.CreateAPIView):
serializer_class = VoteSerializer

Conect the new apiviews to urls.py.

# ...
urlpatterns = [
# ...
path("choices/", ChoiceList.as_view(), name="polls_list"),
path("vote/", CreateVote.as_view(), name="polls_list"),

There is a lot going on here, let us look at the attributes we need to override or set.
• queryset: This determines the initial queryset. The queryset can be further filtered, sliced or ordered by the
view.
• serializer_class: This will be used for validating and deserializing the input and for serializing the
output.
We have used three different classes from rest_framework.generic. The names of the classes are representa-
tive of what they do, but lets quickly look at them.
• ListCreateAPIView: Get a list of entities, or create them. Allows GET and POST
• RetrieveDestroyAPIView: Retrieve and inidvidual entity details, or delete the entity. Allows GET and
DELETE
• CreateAPIView: Allows creating entities, but not listing them. Allows POST.
Create some choices by POSTing to /choices/.

{
"choice_text": "Flask",
"poll": 2
}

The response looks like this

{
"id": 4,
"votes": [],
"choice_text": "Flask",
"poll": 2
}

You can also retrieve the Poll to by doing a GET to /poll/<pk>/. You should get something like this

{
"id": 2,
"choices": [
{
"id": 3,
"votes": [],

20 Chapter 4. Views and Generic Views

 Building APIs with Django and Django Rest Framework, Release 2.0

"choice_text": "Django",
"poll": 2
},
{
"id": 4,
"votes": [],
"choice_text": "Flask",
"poll": 2
}
],
"question": "What do you prefer, Flask or Django?",
"pub_date": "2018-03-12T10:15:55.949721Z",
"created_by": 1
}

If you make a mistake while POSTing, the API will warn you. POST a json with choice_text missing to /
choices/.

{
"poll": 2
}

You will get a response like this

{
"poll": [
"This field is required."
]
}

Check the status code is 400 Bad Request.

4.4 Next Steps

We have working API at this point, but we can simplify our API with a better URL design and remove some code
duplication using viewsets. We will be doing that in the next chapter.

4.4. Next Steps 21

Building APIs with Django and Django Rest Framework, Release 2.0

22 Chapter 4. Views and Generic Views

 CHAPTER 5

More views and viewsets

5.1 A better URL structure

We have three API endpoints

• /polls/ and /polls/<pk>/
• /choices/
• /vote/
They get the work done, but we can make our API more intutive by nesting them correctly. Our redesigned urls look
like this:
• /polls/ and /polls/<pk>
• /polls/<pk>/choices/ to GET the choices for a specfifc poll, and to create choices for a specific poll.
(Idenitfied by the <pk>)
• /polls/<pk>/choices/<choice_pk>/vote/ - To vote for the choice identified by <choice_pk>
under poll with <pk>.

5.2 Changing the views

We will make changes to ChoiceList and CreateVote, because the /polls/ and /polls/<pk> have not
changed.
from rest_framework import generics
from rest_framework.views import APIView
from rest_framework import status
from rest_framework.response import Response

from .models import Poll, Choice

from .serializers import PollSerializer, ChoiceSerializer, VoteSerializer

23
Building APIs with Django and Django Rest Framework, Release 2.0

# ...
# PollList and PollDetail views

class ChoiceList(generics.ListCreateAPIView):
def get_queryset(self):
queryset = Choice.objects.filter(poll_id=self.kwargs["pk"])
return queryset
serializer_class = ChoiceSerializer

class CreateVote(APIView):

def post(self, request, pk, choice_pk):

voted_by = request.data.get("voted_by")
data = {'choice': choice_pk, 'poll': pk, 'voted_by': voted_by}
serializer = VoteSerializer(data=data)
if serializer.is_valid():
vote = serializer.save()
return Response(serializer.data, status=status.HTTP_201_CREATED)
else:
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

And change your urls.py to a nested structure.

#...
urlpatterns = [
path("polls/<int:pk>/choices/", ChoiceList.as_view(), name="polls_list"),
path("polls/<int:pk>/choices/<int:choice_pk>/vote/", CreateVote.as_view(), name=
˓→"polls_list"),

You can see the changes by doing a GET to http://localhost:8000/polls/1/choices/, which should
give you.
[
{
"id": 1,
"votes": [],
"choice_text": "Flask",
"poll": 1
},
{
"id": 2,
"votes": [
],
"choice_text": "Django",
"poll": 1
}
]

You can vote for choices 2, of poll 1 by doing a POST to http://localhost:8000/polls/1/choices/2/

vote/ with data {"voted_by": 1}.
{
"id": 2,
"choice": 2,
"poll": 1,

24 Chapter 5. More views and viewsets

 Building APIs with Django and Django Rest Framework, Release 2.0

"voted_by": 1
}

Lets get back to ChoiceList.

# urls.py
#...
urlpatterns = [
# ...
path("polls/<int:pk>/choices/", ChoiceList.as_view(), name="polls_list"),
]

# views.py
# ...

class ChoiceList(generics.ListCreateAPIView):
def get_queryset(self):
queryset = Choice.objects.filter(poll_id=self.kwargs["pk"])
return queryset
serializer_class = ChoiceSerializer

From the urls, we pass on pk to ChoiceList. We override the get_queryset method, to filter on choices with
this poll_id, and let DRF handle the rest.
And for CreateVote,

# urls.py
#...
urlpatterns = [
# ...
path("polls/<int:pk>/choices/<int:choice_pk>/vote/", CreateVote.as_view(), name=
˓→"polls_list"),

# views.py
# ...

class CreateVote(APIView):

def post(self, request, pk, choice_pk):

voted_by = request.data.get("voted_by")
data = {'choice': choice_pk, 'poll': pk, 'voted_by': voted_by}
serializer = VoteSerializer(data=data)
if serializer.is_valid():
vote = serializer.save()
return Response(serializer.data, status=status.HTTP_201_CREATED)
else:
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

We pass on poll id and choice id. We subclss this from APIView, rather than a generic view, because we competely
customize the behaviour. This is similiar to our earlier APIView, where in we are passing the data to a serializer, and
savig or returnning an error depending on whether the serializer is valid.

5.3 Introducing Viewsets and Routers

Our urls are looking good, and we have a views with very little code duplication, but we can do better.

5.3. Introducing Viewsets and Routers 25

Building APIs with Django and Django Rest Framework, Release 2.0

The /polls/ and /polls/<pk>/ urls require two view classes, with the same seralizer and base queryset. We
can group them into a viewset, and connect the to the urls using a router.
This is what it will look like:

# urls.py
# ...
from rest_framework.routers import DefaultRouter

router = DefaultRouter()
router.register('polls', PollViewSet, base_name='polls')

urlpatterns = [
# ...
]

urlpatterns += router.urls

# views.py
# ...
from rest_framework import viewsets

from .models import Poll, Choice

from .serializers import PollSerializer, ChoiceSerializer, VoteSerializer

class PollViewSet(viewsets.ModelViewSet):
queryset = Poll.objects.all()
serializer_class = PollSerializer

There is no change at all to the urls or to the responses. You can verify this by doing a GET to /polls/ and
/polls/<pk>/.

5.4 Choosing the base class to use

We have seen 4 ways to build API views until now

• Pure Django views
• APIView subclasses
• generics.* subclasses
• viewsets.ModelViewSet
So which one should you use when? My rule of thumb is,
• Use code:viewsets.ModelViewSet when you are goin to allow all or most of crud operations on a model.
• Use generics.* when you only want to allow some operations on a model
• Use APIView when you want to completely customize the behaviour.

5.5 Next steps

In the next chapter, we will look at adding access control to our apis.

26 Chapter 5. More views and viewsets

 CHAPTER 6

Access Control

In this chapter, we will add access control to our APIs, and add APIs to create and authenticate users.
Right now our APIs are completely permissive. Anyone can create, access and delete anything. We want to add these
access controls.
• A user must be authenticated to access a poll or the list of polls.
• Only an authenicated users can create a poll.
• Only an authenticated user can create a choice.
• Authenticated users can create choices only for polls they have created.
• Authenticated users can delete only polls they have created.
• Only an authenticated user can vote. Users can vote for other people’s polls.
To enable the access control, we need to add two more APIs
• API to create a user, we will call this endpoint /users/
• API to verify a user and get a token to identify them, we will call this endpoint /login/

6.1 Creating a user

We will add an user serializer, which will allow creating. Add the following code to serializers.py.

class UserSerializer(serializers.ModelSerializer):

class Meta:
model = User
fields = ('username', 'email', 'password')
extra_kwargs = {'password': {'write_only': True}}

def create(self, validated_data):

user = User(

27
Building APIs with Django and Django Rest Framework, Release 2.0

email=validated_data['email'],
username=validated_data['username']
)
user.set_password(validated_data['password'])
user.save()
return user

We have overriden the ModelSerializer method’s create() to save the User instances. We ensure that we set
the password correctly using user.set_password, rather than setting the raw password as the hash. We also
don’t want to get back the password in response which we ensure using extra_kwargs = {'password':
{'write_only': True}}.
Let us also add views to the User Serializer for creating the user and connect it to the urls.py

# in apiviews.py
# ...
from .serializers import PollSerializer, ChoiceSerializer, VoteSerializer,
˓→UserSerializer

# ...
class UserCreate(generics.CreateAPIView):
serializer_class = UserSerializer

# in urls.py
# ...
from .apiviews import PollViewSet, ChoiceList, CreateVote, UserCreate

urlpatterns = [
# ...
path("users/", UserCreate.as_view(), name="user_create"),
]

We can test this api by posting to /users/ with this json.

{
"username": "nate.silver",
"email": "[email protected]",
"password": "FiveThirtyEight"
}

Which give back this response.

{
"username": "nate.silver",
"email": "[email protected]"
}

Try posting the same json, and you will get a error response (HTTP status code 400)

{
"username": [
"A user with that username already exists."
]
}

28 Chapter 6. Access Control

 Building APIs with Django and Django Rest Framework, Release 2.0

6.2 Authentication scheme setup

With Django Rest Framework, we can set up a default authentication scheme which is applied to all views using
DEFAULT_AUTHENTICATION_CLASSES. We will use the token authentication in this tutorial. In your settings.py,
add this.

REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': (
'rest_framework.authentication.TokenAuthentication',
'rest_framework.authentication.SessionAuthentication',
)
}

You also need to enable rest_framework.authtoken app, the so update INSTALLED_APPS in your set-
tings.py.

INSTALLED_APPS = (
...
'rest_framework.authtoken'
)

Run python manage.py migrate to create the new tables.

REST_FRAMEWORK = {
# ...
'DEFAULT_PERMISSION_CLASSES': (
'rest_framework.permissions.IsAuthenticated',
)
}

Also, dont forget to give excemption to UserCreate view fro authentication by overriding the global setting. The
UserCreate should look as follows.

class UserCreate(generics.CreateAPIView):
authentication_classes = ()
permission_classes = ()
serializer_class = UserSerializer

Note the authentication_classes = () and permission_classes = () to excempt UserCreate

from global authentication scheme.
We want to ensure that tokens are created when user is created in UserCreate view, so we update the
UserSerializer. Change your serailizers.py like this

from rest_framework.authtoken.models import Token

class UserSerializer(serializers.ModelSerializer):

class Meta:
model = User
fields = ('username', 'email', 'password')
extra_kwargs = {'password': {'write_only': True}}

def create(self, validated_data):

user = User(
email=validated_data['email'],
username=validated_data['username']

6.2. Authentication scheme setup 29

Building APIs with Django and Django Rest Framework, Release 2.0

)
user.set_password(validated_data['password'])
user.save()
Token.objects.create(user=user)
return user

6.3 The login API

Since we have added rest_framework.authentication.TokenAuthentication, we will need to set

an header like this Authorization: Token c2a84953f47288ac1943a3f389a6034e395ad940 to
auhenticate. We need an API where a user can give their username and password, and get a token back.
We will not be adding a serailizer, because we never save a token using this API.
Add a view and connect it to urls.

# in apiviews.py
# ...

class LoginView(APIView):
def post(self, request,):
username = request.data.get("username")
password = request.data.get("password")
user = authenticate(username=username, password=password)
if user:
return Response({"token": user.auth_token.key})
else:
return Response({"error": "Wrong Credentials"}, status=status.HTTP_400_
˓→BAD_REQUEST)

# in urls.py
# ...

from .apiviews import PollViewSet, ChoiceList, CreateVote, UserCreate, LoginView

urlpatterns = [
path("login/", LoginView.as_view(), name="login"),
# ...
]

Do you a POST with a correct username and password, and you will get a response like this.

{
"token": "c300998d0e2d1b8b4ed9215589df4497de12000c"
}

POST with a incorrect username and password, and you will get a response like this, with a HTTP status of 400.

{
"error": "Wrong Credentials"
}

30 Chapter 6. Access Control

 Building APIs with Django and Django Rest Framework, Release 2.0

6.4 Fine grained access control

Try accessing the /polls/ API without any header. You will get an error with a http status code of HTTP 401
Unauthorized like this.

{
"detail": "Authentication credentials were not provided."
}

Add an authorization header Authorization: Token <your token>, and you can access the API.
From now onwards we will use a HTTP header like this, Authorization: Token <your token> in all
further requests.
We have two remaining things we need to enforce.
• Authenticated users can create choices only for polls they have created.
• Authenticated users can delete only polls they have created.
We will do that by overriding PollViewSet.destroy and ChoiceList.post.

class PollViewSet(viewsets.ModelViewSet):
# ...

def destroy(self, request, *args, **kwargs):

poll = Poll.objects.get(pk=self.kwargs["pk"])
if not request.user == poll.created_by:
raise PermissionDenied("You can not delete this poll.")
return super().destroy(request, *args, **kwargs)

class ChoiceList(generics.ListCreateAPIView):
# ...

def post(self, request, *args, **kwargs):

poll = Poll.objects.get(pk=self.kwargs["pk"])
if not request.user == poll.created_by:
raise PermissionDenied("You can not create choice for this poll.")
return super().post(request, *args, **kwargs)

In both cases, we are checkeding the request.user against the expected user, and raising as
PermissionDenied if it does not match.
You can check this by doing a DELETE on someone elses Poll. You will get an error with HTTP 403 Forbidden
and response.

{
"detail": "You can not delete this poll."
}

Similarly trying to create choice for someone else’s Poll will get an error with HTTP 403 Forbidden and re-
sponse

{
"detail": "You can not create choice for this poll."
}

6.4. Fine grained access control 31

Building APIs with Django and Django Rest Framework, Release 2.0

6.5 Next steps:

In the next chapter we will look at adding tests for our API and serailizers. We will also look at how to use flake8
and run our tests in a CI environment.

32 Chapter 6. Access Control

 CHAPTER 7

Testing and Continuous Integeration

In this chapater we will test all the views of our API.

Unit testing is always worth the effort. It will gives us the confidence that the code is working perfect at all stages. It
also helps us to identify the bugs in beforehand which will make the development process a cakewalk. Perhaps, test
cases stands as documentation to the whole part of the code.
Now lets us write test cases to our polls application.

7.1 Creating Test Requests

We know that Django’s ‘Requestfactory’ has the capability to create request instances which aid us in testing view
functions induvidually. Django Rest Framework has a class called ‘APIRequestFactory’ which extends the standard
Django’s ‘Requestfactory’. This class contains almost all the http verbs like .get(), .post(), .put(), .patch() etc., in it.
Syntax for Post request:

factory = APIRequestFactory()
request = factory.post(uri, post data)

Now let us test the retrive polls view. And it should look like the following way.

from rest_framework.test import APITestCase

from rest_framework.test import APIRequestFactory

from pollsapi import views

class TestPoll(APITestCase):
def setUp(self):
self.factory = APIRequestFactory()
self.view = views.PollList.as_view()
self.uri = '/polls/'

33
Building APIs with Django and Django Rest Framework, Release 2.0

def test_get(self):
request = self.factory.get(self.uri)
response = self.view(request)
self.assertEqual(response.status_code, 200,
'Expected Response Code 200, received {0} instead.'
.format(response.status_code))

In the above lines of code, we are trying to access the PollList view. It should result us HTTP response code 200.
Now run the test command.
python manage.py test

And it will display the below message.

Creating test database for alias 'default'...
F
======================================================================
FAIL: test_get (pollsapi.test_poll.TestPoll)
----------------------------------------------------------------------
Traceback (most recent call last):
File "/Users/rakeshvidyachandra/code2/django_pollsapi/pollsapi/test_poll.py", line
˓→13, in test_get

.format(response.status_code))
AssertionError: Expected Response Code 200, received 401 instead.

----------------------------------------------------------------------
Ran 1 tests in 0.001s

FAILED (failures=1)

Ouch! Our test failed. This happened because the view is not accessable with out authentication. So we need to create
a user and test the view after getting authenticated.

7.2 Testing authentication

To test authentication, a test user needs to be created so that we can check whether the authentication is working
smooth. Let’s right away create a test user. Save the following code in pollsapi/tests/setup_user
from django.contrib.auth.models import User

def setup_user():
test_user = User.objects.create_user('test', email='[email protected]',
password='test')
test_user.save()
user = User.objects.get(username='test')
return user

Let us use the .force_authenticate method and force all requests by the test client every time it access the view. This
makes the test user automatically treated as authenticated. This becomes handy while testing API and if we dont
want to create a valid authentication credentials everytime we make a request. We shall use the same get() but with
authentication added to it. The whole part looks as follows.
from rest_framework.test import APITestCase
from rest_framework.test import APIRequestFactory, APIClient, force_authenticate

34 Chapter 7. Testing and Continuous Integeration

 Building APIs with Django and Django Rest Framework, Release 2.0

from pollsapi.tests.user_setup import setup_user

from pollsapi import views

class TestPoll(APITestCase):
def setUp(self):
self.factory = APIRequestFactory()
self.client = APIClient()
self.user = setup_user()
self.view = views.PollList.as_view()
self.uri = '/polls/'

def test_get(self):
request = self.factory.get(self.uri)
force_authenticate(request, self.user)
response = self.view(request)
self.assertEqual(response.status_code, 200,
'Expected Response Code 200, received {0} instead.'
.format(response.status_code))

Let us test it now.

python manage.py test

Creating test database for alias 'default'...

.....
----------------------------------------------------------------------
Ran 1 tests in 0.001s

OK
Destroying test database for alias 'default'...

Voilà! The test passed successfully

On the way we shall test the post request in the same manner. We can use the the APIRequestFactory() with post
method this time. The syntax looks like this:

factory = APIRequestFactory()
factory.post(uri, params)

Let us try creating a new poll by sending the ‘question’, ‘choice_strings’ and ‘created_by’ parameters which needs the
Post method. The function looks as follows.

def test_post_uri(self):
params = {
"question": "How are you man?",
"choice_strings": ["Yo Man", "Not Fine"],
"created_by": 1
}
request = self.factory.post(self.uri, params)
force_authenticate(request, user=self.user)
response = self.view(request)
self.assertEqual(response.status_code, 201,
'Expected Response Code 201, received {0} instead.'
.format(response.status_code))

7.2. Testing authentication 35

Building APIs with Django and Django Rest Framework, Release 2.0

And the above function should result us the http code 201 if the test passes succesfully. And we are all done with the
stuff. Time to celebrate with the API :)

7.3 Continuous integration with CircleCI

Maintaining a solid rapport with the ongoing software development process always turns out to be a walk on air.
Ensuring a software build integrity and quality in every single commit makes it much more exciting.
If the current software bulid is constantly available for testing, demo or release isn’t it a developer’s paradise on earth?
Giving a cold shoulder to “Integration hell” the ‘Continuous integration’ process stands out to deliver all the above
assets.
Let us use circle CI software for our App.
We can configure our application to use Circle CI by adding a file named circle.yml which is a YAML(a human-
readable data serialization format) text file. It automatically detects when a commit has been made and pushed to a
GitHub repository that is using Circle CI, and each time this happens, it will try to build the project and runs tests. It
also builds and once it is completed it notifies the developer in the way it is configured.
Steps to use Circle CI:
• Sign-in: To get started with Circle CI we can sign-in with our github account on circleci.com.
• Activate Github webhook: Once the Signup process gets completed we need to enable the service hook in the
github profile page.
• Add circle.yml: We should add the yml file to the project.

7.4 Writing circle.yml file

In order for circle CI to build our project we need to tell the system a little bit about it. we will be needed to add a
file named circle.yml to the root of our repository. The basic options in the circle.yml should contain are language key
which tells which language environment to select for our project and other options include the version of the language
and command to run the tests, etc.
Below are the keywords that are used in writting circle.yml file.
• machine: adjusting the VM to your preferences and requirements
• checkout: checking out and cloning your git repo
• dependencies: setting up your project’s language-specific dependencies
• database: preparing the databases for your tests
• test: running your tests
• deployment: deploying your code to your web servers
• pre: commands run before CircleCI’s inferred commands
• override: commands run instead of CircleCI’s inferred commands
• post: commands run after CircleCI’s inferred commands
Example for circle.yml for python project:

36 Chapter 7. Testing and Continuous Integeration

 Building APIs with Django and Django Rest Framework, Release 2.0

## Customize the test machine

machine:

timezone:
Asia/Kolkata # Set the timezone

# Version of python to use

python:
version: 2.7.5

dependencies:
pre:
- pip install -r requirements.txt

test:
override:
- python manage.py test

From now onwards whenever we push our code to our repository a new build will be created for it and the running of
the test cases will be taken place. It gives us the potential to check how good our development process is taking place
with out hitting a failed test case.

7.4. Writing circle.yml file 37

Building APIs with Django and Django Rest Framework, Release 2.0

38 Chapter 7. Testing and Continuous Integeration

 CHAPTER 8

Appendix

8.1 Testing and using api with Postman

In this chapter, we’ll learn how to use postman for testing our APIs. Postman can be installed as Chrome extension or
Chrome app. With postman you can test almost any API available provided you have access keys/secrets. For any kind
of API endpoints, making a HTTP request is a first and common thing. We’ll see how we can make use of Postman
for this.

8.1.1 Making HTTP request

There are 4 key elements in making an HTTP request.

1. URL: This specifies to which URL we need to make a request for. In other terms where our API endpoint
resides.
2. Method: Each API endpoint has a method which serves it’s purpose. The methods for eg., can be GET for
retrieving some data, POST for creating or updating, DELETE for deleting a record.
3. Headers: Headers provide required information about the request or the response or about the object sent in
the body. Some times we use authentication headers too, in order to access the API endpoint.
4. Body: The request body is where we send the object. The object which may be required for the service.

8.1.2 Response

Response is available in the bottom section, usually in a JSON format, but may also vary depending up on the API
service.

8.1.3 Collections

We can save all the relative API endpoints to collections. In our example, we can save all our polls related endpoints
as a collection or all the users related endpoints as another collection. This way all the APIs are organized.

39
Building APIs with Django and Django Rest Framework, Release 2.0

8.1.4 Authentication

Postman also supports few authentication mechanisms like Basic Auth, Digest Auth and Oauth1. This allows us to
use these authentication methods for the APIs.

8.2 Documenting APIs with Swagger

In this chapater we will see how to use swagger for all the views of our API.
Swagger is a tool used to understand the capabilities of the service without access to source code, documentation, or
through network traffic inspection. In simple terms, with swagger you can see what all API end points are available
for a web application. You can use swagger for testing the requests and responses of the API endpoints.
Now lets us use swagger to our polls application.

8.2.1 Hosting Swagger UI

Firstly we need to host the swagger UI in order to view all the API endpoints. so we’ll first clone the swagger UI from
github.

git clone

As swagger UI is a simple web application, you can host it using any of the hosting methods (apache, nginx, python’s
simple http server ) which you are familiar with.
For simplicity purposes we’ll use python’s SimpleHTTPServer. Change the working directory to the above cloned
folder i.e., swagger-ui and run the following command to start simple http server.

cd swagger-ui
python -m SimpleHTTPServer 8000

Now that we have the swagger UI running and you can see this by going to url http://localhost:8000/ in your browser.

8.2.2 JSON representation of the API

To view all the API endpoints, we need to specify them in a JSON file with the following format. You may call it
pollaspi.json.

{
"swagger": "2.0",
"info": {
"description": "This is a sample server for polls api.",
"version": "1.0.0",
"title": "Polls API",
"termsOfService": "http://example.com/terms/",
"contact": {"email": "[email protected]"},
"license": {"name": "Apache 2.0", "url": "http://www.apache.org/licenses/
˓→LICENSE-2.0.html"}

},
"host": "polls.example.com",
"basePath": "/v2",
"tags": [
{
"name": "polls",

40 Chapter 8. Appendix
 Building APIs with Django and Django Rest Framework, Release 2.0

"description": "Everything about your Polls",

"externalDocs": {"description": "Find out more","url":"http://example.com
˓→ "}
},
{
"name": "choices",
"description": "Access to choices for the polls"
},
{
"name": "user",
"description": "Operations about user",
"externalDocs": {"description": "Find out more about our store","url":
˓→"http://example.com"}

}
],
"schemes": ["http"],
"paths": {
"/polls": {
"get": {
"tags": ["poll"],
"summary": "Get all the polls",
"description": "",
"operationId": "pollList",
"consumes": ["application/json","application/xml"],
"produces": ["application/xml","application/json"],
"parameters": [{
"in": "query",
"name": "body",
"description": "Get all the polls.",
"required": false,
"schema":{"$ref":"#/pollsapi/Poll"}
}],
"responses": {"200":{"description":"Successfull operation"}},
},
"post":{
"tags": ["poll"],
"summary": "Create a new poll",
"description": "Creates a new poll.",
"operationId": "createPoll",
"consumes":["application/json","application/xml"],
"produces":["application/xml","application/json"],
"parameters":[{
"in":"query",
"name":"body",
"description": "Poll object that needs to be added.",
"required": true,
"schema": {"$ref":"#/pollsapi/Poll"}
}],
"responses": {
"200": {"description":"Poll created successfully"}
}
}
},
"/choices": {
"get": {
"tags": ["choice"],
"summary": "Get all the choices",
"description": "",

8.2. Documenting APIs with Swagger 41

Building APIs with Django and Django Rest Framework, Release 2.0

"operationId": "choiceList",
"consumes": ["application/json","application/xml"],
"produces": ["application/xml","application/json"],
"parameters": [{
"in": "query",
"name": "body",
"description": "Get all the choices.",
"required": false,
"schema":{"$ref":"#/pollsapi/Choice"}
}],
"responses": {"200":{"description":"Successfull operation"}},
},
"post":{
"tags": ["choice"],
"summary": "Create a new choice",
"description": "Creates a new choice.",
"operationId": "createChoice",
"consumes":["application/json","application/xml"],
"produces":["application/xml","application/json"],
"parameters":[{
"in":"query",
"name":"body",
"description": "Choice object that needs to be added.",
"required": true,
"schema": {"$ref":"#/pollsapi/Poll"}
}],
"responses": {
"200": {"description":"Poll created successfully"}
}
}
}
}
}

This JSON file should also be available/hosted somewhere in order to access from swagger UI.
Lets use the same python’s SimpleHTTPServer for hosting this JSON file but on a different port. In your terminal cd
to the directory where the JSON file is located and run the following command.
python -m SimpleHTTPServer 8001

Now open the swagger UI in your browser from http://localhost:8000/ and enter http://localhost:8000/pollsapi.json in
the url textbox and click explore to view all the API endpoints of the service.

8.2.3 Note

You may get errors while running both swagger and the JSON file with SimpleHTTPServer locally saying “It may not
have the appropriate access-control-origin settings.” That’s because the server running swagger doesn’t have access
over the other server. In order to resolve this, we need give the access control. We can do this by writing a custom
class and running the server using this. We’ll write the custom class in a seperate file called simple-cors-http-server.py.
#! /usr/bin/env python2
from SimpleHTTPServer import SimpleHTTPRequestHandler
import BaseHTTPServer

class CORSRequestHandler (SimpleHTTPRequestHandler):

def end_headers (self):

42 Chapter 8. Appendix
 Building APIs with Django and Django Rest Framework, Release 2.0

self.send_header('Access-Control-Allow-Origin', '*')
SimpleHTTPRequestHandler.end_headers(self)

if __name__ == '__main__':
BaseHTTPServer.test(CORSRequestHandler, BaseHTTPServer.HTTPServer)

Now we may run this (simple-cors-http-server.py) file to serve the JSON file, which will allow swagger UI to access
this file.

8.3 Documenting API with RAML

In this chapater we will see how to use raml for all the views of our API.
RAML is an acronym for “RESTful API Modeling Language”. It is a YAML based language for describing the
RESTful APIs. RAML contains certain sections for describing the APIs. Each section has it’s purpose and we’ll look
into each one of these by using our polls application.

8.3.1 1. Root

Root section is specifies the basic things like title, baseUri etc. These are applied through out the rest of the API

#%RAML 0.8
---
title: django polls API
baseUri: http://api.example.com/{version}
version: v1
mediaType: application/json

8.3.2 2. Resources

It’s important to consider how your API consumers will use your API. So we’ll list out all the resources that are
available in our API.

/polls:
/choices:
/votes:

Notice that these resources all begin with a slash (/). In RAML, this is how you indicate a resource. Any methods and
parameters nested under these top level resources belong to and act upon that resource.
Now, since each of these resources is a collection of individual objects (specific poll, choice), we’ll need to define
some sub-resources to fill out the collection.
To view all the API endpoints, we need to specify them in a JSON file with the following format. You may call it
pollaspi.json.

/polls:
/{pollId}:

This lets the API consumer interact with the key resource and its nested resources. For example a GET request to
http://api.example.com/polls/1 returns details about the one particular poll whose pollId is 1.

8.3. Documenting API with RAML 43

Building APIs with Django and Django Rest Framework, Release 2.0

8.3.3 3. Methods

The above mentioned resources can be accessed via 4 most common HTTP methods(Verbs).
GET - Retrieve the information defined in the request URI.
PUT - Replace the addressed collection. At the object-level, create or update it.
POST - Create a new entry in the collection. This method is generally not used at the object-level.
DELETE - Delete the information defined in the request URI.
You can add as many methods as you like to each resource of your BookMobile API, at any level. However, each
HTTP method can only be used once per resource.
Nest the methods to allow developers to perform these actions under your resources. Note that you must use lower-case
for methods in your RAML API definition.

/polls:
get:
post:

8.3.4 URI Parameters

The resources that we defined are collections of smaller, relevant objects.

/polls:
/{pollId}:

8.3.5 Query Parameters:

Query parameters are used for filtering a collection. We already have collections-based resource types that are further
defined by object-based URI parameters. We’ll see how we can use query paramters for them.

/polls:
get:
description: Get list of polls
queryParameters:
pollId:

An API’s resources and methods often have a number of associated query parameters. Each query parameter may have
any number of optional attributes to further define it.
Now, we’ll specify attributes for the query parameters we defined above.

/polls:
get:
description: Get list of polls
queryParameters:
pollId:
description: Specify the poll id you want to retrieve
type: integer
example: 1

44 Chapter 8. Appendix
 Building APIs with Django and Django Rest Framework, Release 2.0

8.3.6 Responses:

Responses MUST be a map of one or more HTTP status codes, and each response may include descriptions, examples.

responses:
200:
body:
application/json:
example:
{
"data":
{
"Id": 1,
"question": "Will A be the leader next time?",
"created_by": "user1",
"pub_date": "08:02:2014"
},
"success": true,
"status": 200
}

• genindex
• modindex
• search

8.3. Documenting API with RAML 45