If you know the basics of the field you work in, you can master any technology, reach higher levels as developer, and create better products. In this article, we’ll talk about building APIs and how to do it, step by step. I believe this is going to be useful for all beginner Django developers, as REST APIs are used in every application or piece of software to connect the backend and frontend parts. If you master this, you can build all kinds of products.

Why Use the Django REST Framework?

Many frameworks allow you to easily build APIs for blog applications, but we will use only one – the Django REST framework. It’s convenient in many ways and offers the following advantages:

• Its Web-browsable API is a huge usability win for your developers.
• Authentication policies include packages for OAuth1 and OAuth2.
• Serialization supports both ORM and non-ORM data sources.
• It’s customizable all the way down. Just use regular function-based views if you don't need the more powerful features.
• It has extensive documentation and great community support.
• It’s used and trusted by internationally recognized companies including Mozilla, Red Hat, Heroku, and Eventbrite.

The Step-by-Step Guide To Your API

In this Django REST framework tutorial, we’ll go through all the stages of building an API in great detail.

Set up your development environment

First of all, you have to install Python dependencies for your OS. If you’re using Windows, you can easily install Linux as your secondary OS using this manual or VirtualBox.

To proceed, use pyenv, a simple yet effective Python management tool. It’s our go-to helper. It allows us to change the global Python version, install multiple Python versions, set project-specific Python versions, and manage virtual Python environments.

If you’re using Mac OS or Linux, it should be easy to install:

$ git clone https://github.com/pyenv/pyenv.git ~/.pyenv

Define the environment variable PYENV_ROOT to point to the path where pyenv repo is cloned. Then, add $PYENV_ROOT/bin to your $PATH for access to the pyenv command-line utility.

$ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
$ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc

Add the pyenv unit to your shell to enable shims and autocompletion.

$ echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n  eval "$(pyenv init -)"\nfi' >> ~/.bashrc

Restart your shell so the path changes take effect. Now, you can begin to use pyenv.

$ exec "$SHELL"

At this point, install the latest stable version of Python. Now this...

$ pyenv install 3.7.4

… and create an environment for your project.

$ pyenv virtualenv 3.7.4 blog

Create a Django Project

Now, we’ll create a project folder and navigate to the newly created directory.

$ mkdir projects && cd projects

The next step is to create a Django project. There are several ways to do it.

Personally, I prefer to start projects from a template and use the Django Stars backend skeleton that has been implemented in our web development company. It’s a great tool, since…

• Django projects are formatted according to the Django Stars Code Style requirements,
• django-environ helps keep all configuration in the environment,
• psycopg2 is the default database driver,
• django-extensions/ipython/ipdb is used for debug purposes,
• pytest with pylava are provided for testing, and
• A redefined startapp command allows you to create apps according to Django Stars Code Style requirements.

Here’s the command that will help you start a project from a template:

$ curl https://be.skeletons.djangostars.com/startproject | bash

At the start, you will be offered several Python versions to work with. Select the 3.7 version of Python.

Set the project name to django_blog.

Since we’re going to use the Django Rest Framework, we should select the 3rd option:

If you know you’ll need Celery for you project, you can also choose the first option and press OK.

Anyway, what we just did was create a project from a template. Let’s now navigate to the project name directory:

$ cd django_blog

This is what our project’s structure looks like:

Install packages with requirements

To run the project, we need to install some packages, which are defined in the requirements/dev.txt.
Thus, we install packages with requirements for local development.

Navigate to the API directory:

$ cd api

and install the dependencies.

If you need to add any other packages, just add your package to the dev.txt file for local development, or to common.txt if you need it to be installed on the server.

Next, we will have to add the Pillow package that isn’t included by default in the package we installed. Open the
requirements/common.txt file and add Pillow==6.1.0 to the end. Then run:

$ pip install -r requirements/dev.txt

This is the file that contains a list of all the packages that will be installed.

Bootstrap the Database

Our project needs a database. Most Django developers prefer to use PostgresQL for all environments – i.e., the, development, staging and production systems. Some people use SQLite for local development and PostgreSQL in production. Django ORM allows you to deal with both databases. I strongly recommend that you keep your development station and production as similar as possible and use the same database.

There are several ways to bootstrap a database:

• Using SQLite

To make the database bootstrapping easier, we can use SQLite. It’s an in-process library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine.

All you need to do is open the .env file and replace:

with

Here, we use the django-environ package, which allows you to define the configuration depending on your environment. You can find out more about this approach through The Twelve Factor App.

• Using PostgreSQL

PostgreSQL is a powerful, open-source object-relational database system. It uses and extends the SQL language, and has many features that allow you to safely store and scale the most complicated data workloads. This system is a bit more complicated than SQLite, so you might want to learn more about it.

It’s much easier to install PostgreSQL with Docker – an open-source tool that automates the deployment of an application inside a software container. If you’re not familiar with Docker yet, feel free to check out some instructions on how to install it and work with docker-compose.

Then just open a new tab and run:

$ docker-compose -f build/docker-compose-dev.yml up

Next, we should apply initial migrations:

$ python manage.py migrate

This will apply all previously unapplied migrations to the database which comes with the Django installation.

https://github.com/olegkovalov/django_blog/commit/4f9b20bafc69fb686026d112592c549bd8b6e858

Create a Blog Application

At this point, we’ve already created a Django project, installed packages with requirements, and bootstrapped the database. Which means we can now finally create a blog application using the following command:

$ python manage.py startapp blog

By doing this, you’ve also created a new directory. It will be available in apps/blog.

Now, we should register our application in ‘INSTALLED_APPS’.

Add ’blog’ to your ‘INSTALLED_APPS’ settings placed in ‘api/django_blog/settings/django.py’

Test-Driven Development (TDD) of APIs

As you may have already learned, test-driven development is an approach that focuses on writing tests before you start implementing the business logic of your application. Writing tests first requires you to really consider what do you want from the code. But apart from this, TDD has numerous other benefits:

1. Fast feedback and detailed specification;
2. Reduced time spent on reworking and time spent in the debugger;
3. Maintainable, flexible, and easily extensible code;
4. Shorter development time to market;
5. Increased developer’s productivity;
6. SOLID code; and
7. A clean interface.

Also, TDD tells you whether your last change (or refactoring) broke previously working code. Moreover, it forces radical simplification of the code – you will only write code in response to the requirements of the tests. Also, you're forced to write small classes focused on one thing only. Further on, it allows the design to evolve and adapt to your changing understanding of the problem.

The resulting unit tests are simple and act as documentation for the code. Since TDD use cases are written as tests, other developers can view the tests as examples of how the code is supposed to work.

Before we write tests for our API, let’s take a step back and look at HTTP and how it interacts with the Django REST Framework.

The Hypertext Transfer Protocol (HTTP) is an application protocol for distributed, collaborative, hypermedia information systems. HTTP defines methods like GET, POST, PUT, DELETE, OPTIONS, and HEAD to indicate the desired action that should be performed on the resource you identify. These methods can be defined by the characteristics of safety and idempotency (you can find out more about this here). By agreement, REST APIs rely on these methods, so feel free to use the appropriate HTTP method for each type of action.

Let’s apply it to the resource ‘post’.

How to Write Tests

With the unittests framework, writing tests becomes very easy.

Open the‘api/django_blog/apps/blog/tests/test_models.py’file and add the following code:

Open the‘api/django_blog/apps/blog/models/post.py’file, and define models for Post and Tags:

Our Post model inherits from ‘CoreModel’, so fields and methods defined in ‘CoreModel’ can be added to the ‘Post’ model.

Now, let’s run our first test on the models we’ve created:

$ python manage.py test

This means that the test was run successfully.

Open‘api/django_blog/apps/blog/tests/tests.py’and add tests for your API:

Serializers

A serializer is a framework that allows complex data such as querysets and model instances to be converted to native Python data types. Then, these can then be easily rendered into JSON, XML or other content types. Serializers also work in the opposite direction – deserializing allows parsed data to be converted back into complex types after having validated the incoming data. The serializers in the REST framework work in a way similar to Django's Form and ModelForm classes.

Declare Serializers

Open‘api/django_blog/apps/blog/rest_api/serializers/post.py’and add:

Now, we can use the PostSerializer to serialize a post, or list of posts.

Open‘api/django_blog/apps/blog/rest_api/views/blog_views.py'and add the following code to define API view:

Add the URLs of your endpoints to

‘api/django_blog/apps/blog/rest_api/urls.py’.This will be the URL where your API will be available.

Open‘api/urls.py’and include the blog’s application URLs:

Run Tests

Now, you can test your API using the following command:

$ python manage.py test

Voila! The test has been completed successfully.

Browsable API

API may stand for Application Programming Interface, but humans have to be able to read the APIs, too – someone has to do the programming. Hence the browsable API. With the Django REST Framework, you can generate a human-friendly HTML output for each resource when an HTML format is requested. These pages allow you to easily browse through resources, as well as build in forms to submit data to the resources using POST, PUT, and DELETE.

Let’s test our API with the browsable REST Framework interface. First, start the development server:

$ python manage.py runserver_plus

Then, open your browser of choice and visit this url:

Create a new post with an image file. Fill out the fields “Title” and “Text”, choose an image file in the form at the bottom, and press “POST”. The page will reload with the new content.

If you want to work with a real post, feel free to visit this page.

Versioning

Versioning is a vital part of API design that allows you to improve the representation for the resources of your API and alter behavior between different clients. The REST framework provides a number of different versioning schemes. Versioning is determined by the incoming client request, and may either be based on the request URL or the request headers.

In this example, we use the url path versioning approach.

Open ‘api/django_blog/settings/django.py’ and add:

If the response was changed and you decide to define a different API version, you might handle it as follows:

Documenting Your API

The REST framework provides built-in support for generating OpenAPI schemas. These can be used with tools that allow you to build API documentation.

The browsable API that the REST framework provides allows your API to be entirely self- describing. You can get the documentation for each API endpoint by simply visiting the URL in your browser.

However, there’s also a number of great third-party documentation packages available. For instance, let’s try to integrate drf-yasg. Its goal is to implement as much of the OpenAPI specification as possible (nested schemas, named models, response bodies, enum/pattern/min/max validators, form parameters, etc.) and generate documents that can be used with code-generation tools.

Open the terminal, and type in:

$ pip install -U drf-yasg

Open ‘api/django_blog/settings/django.py’ and add the INSTALLED_APPS ‘drf_yasg’ package:

Also, we should include URLs, for generated documentation:

You can find the documentation on your API in this document.

If you want to implement new features or play around, feel free to clone or fork my git hub repo.

Now, let’s see why what we’ve learned about why Django REST Framework is so practical for building APIs. The Django REST Framework (DRF) provides a large set of features:

• Easy creation of resources with Generic Views – they allow you to quickly build API views that map closely to your database models;
• An authentication mechanism associates an incoming request with a set of identifying credentials;
• Permissions grant access to any authenticated user, and deny access to any unauthenticated user;
• Throttling indicates a temporary state, and is used to control the rate of requests that clients can make to an API;
• Caching through cache utilities provided by Django;
• Filtering allows you to restrict the items that are returned in response;
• Pagination allows you to choose how large result sets will be split into individual pages of data;
• Status Codes – the REST framework includes a set of named constants you can use to make your code more transparent and readable;
• Versioning to alter behavior between different clients; and
• The Browsable API enables you to read the APIs.

If you still have questions and would love to learn more, there’s plenty of great Django REST API tutorials and resources for self-improvement. Here’s a reading list our software development team Django Stars highly recommends. And if by any chance you have to deal with nested objects, here’s a useful library that might come in handy. Also, feel free to visit the django_blog repository for ideas and inspiration. But as I said before, if you know your basics well, you can build upon this knowledge. And considering how universal APIs are, you’ll be able to work with any kind of product, which will make you an indispensable team member and a universal soldier of software development.

This guide about how to develop APIs with Django REST Framework was originally posted on Django Stars blog. Written by Oleg Kovalyov - Software Engineer Lead at Django Stars