How to Develop APIs with Django REST Framework [Step-by-Step Guide]

If you know the basics of the field you work in, you can master any technology, reach higher levels as a developer, and create better products.

In this article, we’ll talk about how develop APIs with Django REST framework by 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.

The experts of our company have repeatedly used Django REST Framework in their projects, which you can see in our portfolio.

Why Use the Django REST Framework for API Development?

Many frameworks allow you to easily build APIs for blog applications, but we will use only one – the Django REST framework (DRF). 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.

Read Also: Debugging Python Applications with the PDB Module
REST, which stands for ‘REpresentational State Transfer,’ is one of the programming architectures that define how Django APIs work. The term ‘RESTful’ is used for web services that adhere to REST constraints. In a nutshell, while DRF makes it easy to work with Django, RESTful APIs work according to REST. By the way, find out why we use Django.

Difference between Django and Django REST Framework

Despite the similarity in names, Django and Django REST frameworks serve different purposes.

Django is a high-level Python web framework encouraging rapid development and clean, pragmatic design. It facilitates the creation of robust web applications with minimal code, providing tools to handle the site’s administrative tasks. Django’s primary goal is to ease the creation of complex, database-driven websites.

For its part, DRF is a powerful and flexible toolkit used to build Web APIs on top of Django. While Django deals with the overall web application, including both frontend and backend components, DRF is used to build RESTful APIs that allow interaction and communication between different software components. With DRF, it’s easier to design the CRUD operations and use a Django Server as a REST API. Django Rest framework leverages Django’s capabilities to facilitate the development of scalable, maintainable, and secure APIs. It adheres to Django’s principles like DRY (Don’t Repeat Yourself) and emphasizes reusability and modularity.

In essence, DRF extends Django’s functionalities. When used together, these tools can significantly accelerate the development process, maintaining a balance between robustness and simplicity.

The Step-by-Step Guide To Your API in Django

In this Django restful api tutorial, we’ll go through all the stages of building an API in great detail. Please note that you will not find a more detailed Django REST framework tutorial even on w3schools.

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 step of the Django API tutorial, 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 Django REST framework 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.

Further according to the Django REST tutorial, 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 your 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 Django 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

Next, according to the Python Django REST API tutorial, 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.

Read Also: Python Descriptors Tutorial

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

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, Django REST APIs rely on these methods, so feel free to use the appropriate HTTP method for each type of action in your Django REST API project.

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.

N.B.: Remember to launch ‘./manage.py makemigrations’ and ‘./manage.py migrate’ commands after each model variation.

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 Django REST framework 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.

It’s time to build your REST APIs with Django

Now, let’s see what we’ve learned about in this Django REST Framework API tutorial. Why is it so practical for building APIs? This framework 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 Python 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.