How to build an API using Django Rest Framework

Django REST Framework is a powerful and flexible toolkit for building web APIs

The purpose of this article is to help you learn new staff and practicies while creating new things. The goal is to create a To-do List application where we can store our thoughts about things we want to do for today, tomorrow or someday.

Here are some reasons why to use  DRF


- It is used and trusted by internationally recognised companies including Mozilla, Red Hat, Heroku, and Eventbrite.
- It's Customizable all the way down
- The huge usability of the web browsable API
- Serialization that supports both ORM and non-ORM data sources
- Extensive documentation and huge community support

You can read more about the Django REST Framework here

What we will need

For the Django REST Framework we need Python and Django Web Framework
Let's go ahead and install  the requirements

First things First!
Create a folder for you project, I will name mine 'todolist'

$ mkdir todolist

Then create a virtual environment for this project using virtualenv and Python 3.
The use of virtual environment is strongly recommended

 $ virtualenv -p /usr/local/bin/python3 venv

Now that we have created our environment there is one last thing we need to do before any installation attempt. Activate it

$ source venv/bin/activate

You'll see your prompt with a (venv) prefix, like this:

(venv) pycat@ghost:~/workspace/APIs/todolist$

Now we are ready ti install the dependencies. Lets' install Django using pip :

$ pip install  Django

And then finaly create the our project. You can give a whatever name to your project

$ django-admin startproject todorest .

* dont forget the dot at the end

Now Django already structered our basic project file witch looks like this

todorest
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
└── manage.py

There is one more requirement we need to install - DRF

$ pip install djangorestframework

Include DRF into settings file:

# Application definition

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
]

 

Time to create the REST API app

We will create a new django application with the name app. Yeah, that's right
the REST API will get started as a simple django application

$ ./manage.py startapp api

 

Include api into settings file:

# Application definition

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'api',
]

 

Lets Rock'n Roll

"Do nothing until you have a test"

The best way to do code testing is by using Test-Driven Development (TDD). This is how it works:

Write a test. – The test will flesh out some functionality in your app

Then, run the test – The test should fail, since there's no code to make it pass.

Write the code – To make the test pass

Run the test – If it passes, you are confident that the code you've written meets the test requirements

Refactor code – Remove duplication, prune large objects and make the code more readable. Re-run the tests every time you refactor the code

Repeat – That's it!

 

Open the test.py file inside the appi directory and add the following code.
The following code imports the testcase from django.test library and tests
whether the the Model TodoList can create a list. It is a simple test:

 

from django.test import TestCase
from .models import  TodoList

class ModelTestCase(TestCase):
    # lets define a test suit for the todolist model


    def setUp(self):
        # define the test client and other test
        self.todolist_name = "Goto the supermarket"
        self.todolist = TodoList(name="todolist_name")


    def test_model_can_create_a_list(self):
        objects_count = TodoList.objects.count()
        self.todolist.save()
        objects_new_count = TodoList.objects.count()
        self.assertNotEqual(objects_count, objects_new_count)

 

We need to define the Model before we run the above test. Open the models.py file and add the folowing code:

from django.db import models

# Create your models here.

class TodoList(models.Model):
    pass

Now it is time to run the tests.

(venv) pycat@ghost:~/workspace/APIs/todolist$ ./manage.py test

 

After that you will get nothing but errors but don't worry, that;s excactly the point of Test Driven Development

We will build the Model code while we're trying to solve the test errors ;)

Edit the models.py file and add the following:

from django.db import models

# Create your models here.

class TodoList(models.Model):
    name = models.CharField(max_length=255, blank=False, unique=True)
    created = models.DateTimeField(auto_now_add=True)
    modified = models.DateTimeField(auto_now=True)

    def __str__(self):
        return "{}".format(self.name)

 

Migrate:

$ ./manage.py makemigrations
$ ./manage.py migrate

 

And run the test again:

$./manage.py tests

Bingo! This test passes!!!

 

Serialization Time

Serializers allow complex data such as querysets and model instances to be converted to native Python datatypes that can then be easily rendered into JSON, XML or other content types. Serializers also provide deserialization, allowing parsed data to be converted back into complex types, after first validating the incoming data. You can read more about DRF Serializers here

The ModelSerializer class provides a shortcut that lets you automatically create a Serializer class with fields that correspond to the Model fields. Create a file serializers.py and fill in the following code:

from rest_framework import serializers
from .models import TodoList

class TodoListSerializer(serializers.ModelSerializer):

    class Meta:
        model = TodoList
        fields = ('id', 'name', 'created', 'modified')
        read_only_fields = ('created', 'modified')

 

That's it. This serializer maps the Model instance into JSON format!

 

Building the Views

First write the tests. Writing the tests seems scary at first but not if toy work according to strategy. How do you know what to test? Just think about and make a list of things that you want to implement. For the views we need to handle the follwing:

♦ Create a todo list –  POST request

♦ Read a todo list –  GET request

♦ Update a todo list –  PUT request

♦ Delete a todo list –  DELETE request

We're going now to write the test basing to the above list.

Add the code below in your tests.py :

# test views imports
from rest_framework.test import APIClient
from rest_framework import status
from django.core.urlresolvers import reverse

# define the ViewTestCase testsuite right after the ModelTestCase
class ViewTestCase(TestCase):
    def setUp(self):
        self.client = APIClient()
        self.todolist_data = {'name': 'Go to the supermarket'}
        self.response = self.client.post(
            reverse('create'),
            self.todolist_data,
            format="json"
        )

    def test_api_can_create_list(self):
        self.assertEqual(self.response.status_code, status.HTTP_201_CREATED)

If you go ahaid you'll se tha running the test fails. That's ok because we havent implement yet the URconf and the views that satisfy this request. So lets implement them

Edit the views.py

from django.shortcuts import render
from rest_framework import generics

from .serializers import TodoListSerializer
from .models import TodoList

# Create your views here.
class CreateView(generics.ListCreateAPIView):
    qyeryset = TodoList.objects.all()
    serializer_class = TodoListSerializer

    def create_performance(self,serializer):
        # save the POST data when user creates a new todo list

        serializer.save()


 We make use of the ListCreateAPIVIew witch is a DRF class-based view that provides GET and POST handlers. One of the key benefits of class-based views is the way they allow you to compose bits of reusable behavior. REST framework takes advantage of this by providing a number of pre-built views that provide for commonly used patterns. You can read more about DRF Generic Views here.

 

Time For URL Configuration

URLs are the interface of our API to the outside world. A clean and usable URL scheme is an important detail in a high-quality Wev Application. With DRF we can design URLs however we want with no framework limitations.

We will create a urls.py file on the api directory. This is where we define our url patterns.

from django.conf.urls import url, include
from .views import CreateView

urlpatterns = {
    url(r'^todolist/$', CreateView.as_view(), name="create")
}

 

We'll also have to include our api.urls to the main apps urls so tha it points to our
API. Go to the todorest folder edit the urls.py.  Our urls.py now should look
like this:

from django.conf.urls import url, include
from django.contrib import admin

urlpatterns = [
    url(r'^admin/', admin.site.urls),

    # finaly we add the url to the main app's urls.py so that it point to the APIapp
    url(r'^', include('api.urls')),
]

 

Our tests should be working now.

(venv) pycat@ghost:~/workspace/APIs/todolist$ ./manage.py test

Creating test database for alias 'default'...

..

----------------------------------------------------------------------

Ran 2 tests in 0.017s

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

 

Spin up the server!

$ ./manage.py runserver

We assume here that we have allready activated a virtualenv with python3. It's the same typing:

$ python3 manage.py runserver

If we see the following console means that everything goes well and the app is running smoothly

(venv) pycat@ghost:~/workspace/APIs/todolist$ ./manage.py runserver
Performing system checks...

System check identified no issues (0 silenced).
April 04, 2017 - 09:33:08
Django version 1.10.6, using settings 'todorest.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Now let's open the todo list url on the browser to check out how it works. Type this or click it to open  http://localhost:8000/todolist/

If everything has gone well you should see something similar to this:

Time check how the api works. Go ahead and insert a Todo List. Then you should see something like this:

GET, UPDATE and DELETE actions

Test goes First as usual:

def test_api_can_get_list(self):
    todolist = TodoList.objects.all()
    response = self.client.get(
        reverse('details'),
        kwargs = {'pk': todolist.id}, format="json"
    )

    self.assertEqual(response.status_code, status.HTTP_200_OK)
    self.assertContains(response, todolist)

def test_api_can_update_list(self):
    todolist = TodoList.objects.get()
    update_list = {'name': 'New list item name'}
    response = self.client.put(
        reverse('details', kwargs={'pk': todolist.id}),
        update_list, format='json'
    )
    self.assertEqual(response.status_code, status.HTTP_200_OK)

def test_api_can_delete(self):
    todolist = TodoList.objects.get()
    response = self.client.delete(
        reverse('details', kwargs={'pk': todolist.id}),
        format='json',
        follow=True)

    self.assertEquals(response.status_code, status.HTTP_204_NO_CONTENT)

Running this tests we get 3 fails. That's absolute normal. We need to write some code in order get rid of those test errors. If we pay some attention on the erro logging we will find out that threre are some view problems and also some url resorvers that need configuration.

First we will implement our details view using RetrieveUpdateDestroyAPIView a Generic view witch is used for read-write-delete endpoints to represent a single model instance. It Provides GET, PUT, PATCH and DELETE method handlers. You can read more in the documentation

Add the following code in your views.py

class DetailsView(generics.RetrieveUpdateDestroyAPIView):

    queryset = TodoList.objects.all()
    serializer_class = TodoListSerializer

 

Now add the url configuration for this view. Our urls.py now should look like this:

 

from django.conf.urls import url, include

from .views import CreateView DetailsView

urlpatterns = {
    url(r'^todolist/$', CreateView.as_view(), name="create")

    url(r'^todolist/(?P<pk>[0-9]+)/$',DetailsView.as_view(), name="details"),
}

 

That's It!!

 

Why should I use TDD?

In software development, testing is paramount. So why should I do it, you ask?

Tests have a short feedback loop, enabling you and your team to learn faster and adjust

Less time is spent debugging, allowing you to spend more time writing code

Tests act as documentation for your code!

They improve code quality while reducing bugs

After refactoring code, your tests will tell you whether the change has broken previously working code, and...

Tests are documentation Ever suffered from not knowing how a newly acquired and quite complex system works? Well-written unit tests show how the individual classes work together to achieve one or more business tasks. Analysing that code permitts new developers figure out the internal workings of the system quickly.

Unit tests help you to get zoned. Programmers and HR managers dream of the concept of the zone – a mental state where effectiveness reaches the highest possible level. Getting into it tends to require some introductory work, which is subject related but not particularly complex. Coding unit tests is an ideal example for such ‘menial tasks

It prevents catastrophic errors If you release an application where a crucial feature doesn’t work it can result in huge monetal losses. A reliable set of tests mitigates this by ensuring that no products get shippeThis is how it works:

Testing Is Fun. If you thrive on challenges, then testing is a lot of fun.

 

Comments

SEARCH BLOG

SIMILAR POSTS

POPULAR TAGS

======= >>>>>>> master

+30 211 790 2526

Find me

kabardi.cat@gmail.com