Building a Web App: Django Rest Framework API Development — Part 3

This post is part of a series of mine on building web applications from the ground up. It covers everything you need to know to completely finish a web application. If you haven’t been following the series, please go back and read part 1

Recap

In the last part of this series we successfully setup our API project. We made a Git repository, initialized our overarching project files, and developed a small amount of the API. Now we can continue to develop the models and views in our app.

Create a new Django App

In the last part of the series, we created a test endpoint under the main project, but we really should create a new Django app for related models and views.

But before we get too far, why don’t we delete the test_view.py file we made in the last part and the references to it in urls.py.

Now, create a new Django app with the following command.

python manage.py startapp todo

Be sure to add the “todo” app to the INSTALLED_APPS list in settings.py.

Creating Models

Now that we have a shiny new app to play with, let’s make some models for it.

Some of you might still be wondering, what the **** is a model? Simply put, a model helps Django map Python objects to database tables.

Since we’re building a ToDo app, I think we should start by making a ToDo list. But what composes a ToDo list? Well, there’s the list and uh… list items.

When we created a new app, it should have made a file located at src/todo/models.py. Edit that file to add our models.

# import the django models module
from django.db import models

# This class will more or less map to a table in the database
class ToDoList(models.Model): 
    """ A Model for representing single line items in a ToDo List. """
    # defines a required text field of 100 characters. 
    title = models.CharField(max_length=100)

# This class will more or less map to a table in the database
class ToDoListItem(models.Model):
    """ A Model for representing single line items in a ToDo List. """
    # Define a foreign key relating this model to the todo list model.
    # The parent will be able to access it's items with the related_name
    # 'items'. When a parent is deleted, this will be deleted as well. 
    todo_list = models.ForeignKey(
        'ToDoList',
        related_name='items', on_delete=models.CASCADE
    )
    # this defines a required title that cannot be more than 100 characters.
    title = models.CharField(max_length=100)
    # this defines an arbitrary length text field which is optional.
    description = models.TextField(blank=True, default='')

Now that the models are defined, we have to do a migration in Django. You can do this with the following commands.

python manage.py makemigrations todo
python manage.py migrate

This will generate SQL files that are then run on the database to apply the changes you made to your model. Afterward, your ToDo models should now be able to be used in the application.

Test Your Models

Writing tests is always a good practice. However, I’ll be the first to admit that I don’t always write tests for every model in my Django app. But today we will!

When we created our app, it made a file, src/todo/test.py. However, if you write a lot of tests, this can easily get messy. Trust me, I know. So before we start writing tests, let’s just delete this file, and create a new folder named test in the todo/ folder. Within that folder, create an empty file named __init__.py. As a reminder, this is how Python recognizes the test/ folder as a package.

Now, make a new file src/todo/test/test_models.py file and add the following.

from django.test import TestCase
from todo.models import ToDoList, ToDoListItem

class ToDoListTestCase(TestCase):
    """Tests for the todo list models"""

    def test_todo_list(self): 
        """Test creating a todo list with no items"""
        # create a todo list object (this saves it to the database)
        ToDoList.objects.create(title="Test List")
        # verify the object was saved
        todo_list = ToDoList.objects.get(title="Test List")
        # verify the data is accurate and exists
        self.assertEqual(todo_list.title, "Test List")
        # delete the list 
        todo_list.delete()
        # try to retrieve the todo list and make sure it's not there
        try: 
            retrieved_list = ToDoList.objects.get(title="Test List")
        # catch the DoesNotExist error that we're hoping to get
        except ToDoList.DoesNotExist: 
            retrieved_list = None
        self.assertEqual(retrieved_list, None)

This is a good basic test for a ToDoList. But we aren’t testing items at all here. Let’s add a quick test to verify items function how we expect them to.

def test_todo_list_items(self):
    """
    This test creates a todo list, adds an item to it, and verifies
    that item is accessible through the 'items' related name. Then,
    it deletes everything.
    """ 
    todo_list = ToDoList.objects.create(title="Test") 
    todo_list_item = ToDoListItem.objects.create(
        todo_list=todo_list,
        title="Test Item",
        description="This is a test todo list item")

    # verify that the related name returns the todo_list item
    self.assertEqual(todo_list.items.count(), 1)
    self.assertEqual(todo_list.items.first(), todo_list_item)

    # now delete the list. This should delete any items with it
    todo_list.delete()
    # verify the todo list item was deleted with the list
    # due to the CASCADE attribute we gave our model
    try:
        retrieved_item = ToDoListItem.objects.get(title="Test Item")
    except ToDoListItem.DoesNotExist:
        retrieved_item = None
    self.assertEqual(retrieved_item, None)

Now that the tests are created, you can run them with the following command.

python manage.py test

Create a Serializer

Serializers help transform data from your models into JSON, which is returned by the API. Conversely, it also helps to parse data POSTED to your API and create new models.

Create a new file src/todo/serializers.py.

# import the django rest framework serializers
from rest_framework import serializers
# import our models
from todo import models

class ToDoListItem(serializers.ModelSerializer):
    """
    Create the first serializer for ToDoListItems
    This is a model serializer, so it will autogenerate a
    full serializer from the model.
    """
    class Meta:
        # specify the model to use
        model = models.ToDoListItem
        # specify the field names we want to show in the api
        fields = ('id', 'todo_list_id', 'title', 'description')

class ToDoList(serializers.ModelSerializer):
    """
    Create a second serializer for the ToDoList model.
    This will have the above serializer nested within it.
    """
    items = ToDoListItem(many=True)

    class Meta:
        # specify the ToDoList model
        model = models.ToDoList
        # specify the fields from ToDoList that we want our API to return/consume
        fields = ('id', 'title', 'items')

    def create(self, validated_data):
        """
        Override the default create method so that we can serialize
        whole ToDoList objects with ToDoListItems.

        :param validated_data: A Dictionary of values to use for object creation.
        :type validated_data: OrderedDict
        :returns ToDoList: A ToDoList model object
        """
        # remove the value of items from the ToDoList validated data. We'll use this later
        items_data = validated_data.pop('items')
        # create a new ToDoList with the validated data passed in
        todo_list = models.ToDoList.objects.create(**validated_data)
        # for each item in the 'items' validated data
        for item_data in items_data:
            # modify it's validated data to reference the ToDoList we just made
            item_data['todo_list_id'] = todo_list.id
            # Create the ToDoListItem with the item data
            models.ToDoListItem.objects.create(**item_data)
        # after this return the todo_list we made
        return todo_list

Testing your Serializers

Moving on, we now have a serializer created. And we think it works. But to be sure, we should write a test for it.

Create a new test file at test/test_serializers.py with the following contents.

from django.test import TestCase
from todo import serializers

class ToDoListTestCase(TestCase):
    """Tests for the todo list models"""

    def test_todo_list_create(self):
        """
        Define some json data we expect to receive and use the 
        serializer to parse it into models. Test the models
        to make sure they're correct.
        """
        # define data that resembles what would come through the API.
        # A Python dictionary is often what JSON data is parsed into initially.
        data = {
            'title': 'Test List',
            'items': [
                {
                    'title': 'Test Item 1',
                    'description': 'This is test item 1'
                },
                {
                    'title': 'Test Item 2',
                    'description': 'This is test item 2'
                }
            ]
        }

        # pass the data into the serializer to try and parse it
        serializer = serializers.ToDoList(data=data)
        # verify that the serializer thinks the data is valid
        self.assertTrue(serializer.is_valid())

        # get the object parsed from the serializer
        todo_list = serializer.save()

        # verify the title is correct
        self.assertEqual(todo_list.title, 'Test List')
        # verify it has two items
        self.assertEqual(todo_list.items.count(), 2)

This will feed data into our serializers and make sure that it parses it correctly. As an additional excersize, try writing some tests that prove invalid data is not parsed correctly.

Run the tests again with the following command.

python manage.py test

Creating Views

Django views define what API endpoints will do. These API endpoints will either get data, post new data, update existing data, or delete data.

In views.py, add the following views which will allow us to get and create todo lists.

from django.shortcuts import render
from django.http import Http404
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status

from todo import serializers, models

class ToDoList(APIView):
	"""
	List all todo lists when the GET method is called. 
	Add new ToDo lists when the POST method is called.
	Delete a ToDo list when the DELETE method is called.
	"""

	def get(self, request, format=None):
		"""
		Return a list of all the ToDoList objects in the database.
		"""
		# query the database for all instances of the ToDoList model
		todo_lists = models.ToDoList.objects.all()

		# serialize the data into a returnable format
		serializer = serializers.ToDoList(todo_lists, many=True)

		return Response(serializer.data)

	def post(self, request, format=None):
		"""
		Creates a new ToDoList with the given request data.
		"""
		# deserialize the data from the request
		serializer = serializers.ToDoList(data=request.data)
		# if the data validation done by the serialize passes
		if serializer.is_valid():
			# then save the ToDoList to the database and return the resulting ToDoList
			serializer.save()
			return Response(serializer.data)
		else:
			# Throw a 400 error if the serializer detected the data wasn't valid
			return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

	def delete(self, request, todo_list_id, format=None):
		"""Deletes a ToDoList from the database"""
		# do this in a try block to catch errors if todo_list_id isn't real
		try:
			# if the list is real then delete it
			todo_list = models.ToDoList.objects.get(id=todo_list_id)
			todo_list.delete()
			return Response(status=status.HTTP_204_NO_CONTENT)
		# catch the DoesNotExist error and return an Http error
		except models.ToDoList.DoesNotExist:
			raise Http404

class ToDoListItem(APIView):
	"""
	Endpoints for adding/deleting individual ToDoListItems.
	"""

	def post(self, request, todo_list_id, format=None):
		"""Add new ToDoList items to an existing ToDoList"""
		# do this in a try block in case the todo_list_id is not real
		try:
			# Query the db for the existing list
			todo_list = models.ToDoList.objects.get(id=todo_list_id)
			# deserialize the data from the request
			serializer = serializers.ToDoListItem(data=request.data)

			# if the ToDoListItem is valid then add the list id and save it
			if serializer.is_valid():
				serializer.validated_data['todo_list_id'] = todo_list_id
				serializer.save()
				return Response(serializer.data)

			else:
				# return an HTTP 400 error if the data was not correct
				return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

		# ALWAYS catch your DoesNotExist errors :)
		except models.ToDoList.DoesNotExist:
			raise Http404

	def delete(self, request, todo_list_item_id, format=None):
		"""Deletes a ToDoListItem from the database"""
		# try to find the ToDoListItem with the id
		try:
			item = models.ToDoListItem.objects.get(id=todo_list_item_id)
			# if the item exists then delete it
			item.delete()
			return Response(status=status.HTTP_204_NO_CONTENT)
		# return the 404 error if it doesn't exist
		except models.ToDoListItem.DoesNotExist:
			return Http404

Now we have several views defined. Unfortunately, these don’t really do a heck of a lot unless we map URLs to them. Open your urls.py file and change it so it looks like the following:

from django.conf.urls import url
from rest_framework.urlpatterns import format_suffix_patterns
from todo import views

urlpatterns = [
    # Maps to ToDoList.get and ToDoList.post
    url(r'^todo_lists

This maps specific URL patterns to the different views. For example, now if I make the request GET localhost:8000/todo_lists, I will receive a list of all the ToDoLists. But don't take my word for it, let's test it out!

Testing your Views

Now, lets write some basic tests for our API routes. To do this, we're going to take advantage of Django's Test Client.

Create a new file at test/test_views.py and add the following.
import json
from django.test import TestCase, Client
from django.test import Client
from todo import models

class ToDoListTestCase(TestCase):
    """Tests for the todo list models"""

    def setUp(self):
        """Initialize the TestCase with a test client"""
        self.client = Client()
        self.test_list = models.ToDoList.objects.create(title='Test ToDo List')
        super(ToDoListTestCase, self).setUp()

    def test_todo_list_item_post_delete(self):
        """
        Test the /todo_list//items POST method to add items
        and the /todo_list/items/ DELETE method to
        remove todo list items.
        """
        # define the data to post
        post_data = {
            'title': 'Test List Item',
            'description': 'This is a test.'
        }

        # post a new ToDoListItem
        response = self.client.post(
            '/todo_lists/{0}/items'.format(self.test_list.id),
            json.dumps(post_data),
            content_type='application/json')

        # always check the response status code
        self.assertEqual(response.status_code, 200)

        # get the id of the saved object we posted
        list_item_id = response.data['id']

        # now try and delete it
        response = self.client.delete('/todo_lists/items/{0}'.format(list_item_id))

        # verify the response we got is a 204 no content
        self.assertEqual(response.status_code, 204)

    def test_todo_list_get_post_delete(self):
        """
        Test the /todo_lists GET POST and DELETE methods.
        """
        # define data in a dictionary to post to the API
        post_data = {
            'title': 'Test List',
            'items': [
                {
                    'title': 'Test Item 1',
                    'description': 'This is test item 1'
                },
                {
                    'title': 'Test Item 2',
                    'description': 'This is test item 2'
                }
            ]
        }

        # try to post the data as json
        response = self.client.post('/todo_lists', 
            json.dumps(post_data),
            content_type="application/json")

        # always assert that your status code is what you expect
        self.assertEqual(response.status_code, 200)

        # get the todo list id from the response
        todo_list_id = response.data['id']

        # now retrieve all the todo lists
        response = self.client.get('/todo_lists')
        self.assertEqual(response.status_code, 200)
        # get the todo lists from the endpoint
        received_todos = response.data

        # search for the todo list we posted
        is_present = False
        found_list = None
        for received_todo_list in received_todos:
            if received_todo_list['id'] == todo_list_id:
                is_present = True
                found_list = received_todo_list
                break

        # assert that the list we posted was indeed found
        self.assertTrue(is_present)
        # verify the list title is correct
        self.assertEqual(found_list['title'], post_data['title'])
        # verify the length of the items list is correct
        self.assertEqual(len(found_list['items']), len(post_data['items']))

        # for each ToDoListItem verify it's data is correct
        for i in range(0, len(found_list['items'])):
            found = found_list['items'][i]
            expected = post_data['items'][i]
            self.assertEqual(found['title'], expected['title'])
            self.assertEqual(found['description'], expected['description'])
        
        # delete the todo list now
        response = self.client.delete('/todo_lists/{0}'.format(todo_list_id)) 
        # verify we get a 204 HTTP No Content Response
        self.assertEqual(response.status_code, 204)

And that's it! Run the tests again, and watch the glorious output.

Using Postman

But what if I just want to poke around at my API a little manually? To manually send requests to my APIs, I use a tool called Postman. This lets you create and save requests within this application and execute them against your API. However, I don't want to make this tutorial about using Postman, as it's an unnecessary step and just something I thought I'd mention. Instead, check out their awesome documentation.

Conclusion

Awesome! We now have a functioning Django API for our ToDo project. If you want to keep going, there's some functionality that you could still add.

As an exercise, try doing the following:

  • An endpoint for getting single ToDoListItems.
  • Endpoints for updating existing ToDoLists and ToDoListItems
  • Additional testing in test_models.pytest_serializers.py, and test_views.py.
  • Refactor the code to have a separate file per model/view/serialzer. E.g. create a views/ folder with a file for each view class within it. It's the best practice to split Python files before they get too large. Splitting up these files by classes just makes the most sense.

I hope this helped you to get started creating RESTful APIs with Django.

If you would like to see the entire project setup, the GitHub repository is here.

As a reminder, this tutorial is part of a series on Building a Web App From the Ground Up. So far we've done our due diligence with designing our application, we've initialized our API project, and now we've developed it as well.

The next part of this series is going to cover building a lightweight client-side app with ReactJS. You'll probably also need to add some authentication to your API, so check out my post on adding authentication with the Django rest framework. Check out Part 4 next.

Stuck? Have additional questions? Want to offer up some of your own input? Leave a comment below and I'll get back to you.