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

Jul 5, 2024
17 min read
How to Develop APIs with Django REST Framework [Step-by-Step Guide]
Oleg Kovalyov
Oleg Kovalyov
Backend Tech Lead

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.

Django: The Best Quality-Value Ratio.

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:

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.

Tech consultancy: Get advantage.

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 ~/.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 | bash

At the start, you will be offered several Python versions to work with. Select the 3.7 version of Python.
How to Develop APIs with Django REST Framework [Step-by-Step Guide] 1
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:
How to Develop APIs with Django REST Framework [Step-by-Step Guide] 2
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:


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 migrate

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

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 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/’

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/’file and add the following code:

Open the‘api/django_blog/apps/blog/models/’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 ‘./ makemigrations’ and ‘./ migrate’ commands after each model variation.

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

$ python test

This means that the test was run successfully.

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


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/’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/'and add the following code to define API view:

Add the URLs of your endpoints to

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

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

Run Tests

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

$ python test

Voila! The test has been completed successfully.
Boost your web development.

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 runserver_plus

Then, open your browser of choice and visit this url:
How to Develop APIs with Django REST Framework [Step-by-Step Guide] 3
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.
How to Develop APIs with Django REST Framework [Step-by-Step Guide] 4
If you want to work with a real post, feel free to visit this page.


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/’ 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/’ 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.
How to Develop APIs with Django REST Framework [Step-by-Step Guide] 5
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.

Thank you for your message. We’ll contact you shortly.
Frequently Asked Questions
Does Django Stars provide Django Rest framework projects services?
Yes, Django Stars, as a software development company, offers services in Django REST framework projects. We specialize in building high-quality, scalable web applications using Django and the Django REST framework, ensuring that our clients receive efficient, robust, and customized solutions tailored to their specific needs. Our expertise in these technologies allows us to deliver top-notch services in developing RESTful APIs and web applications.
How much does Django restful api development cost?
The cost of developing a Django RESTful API depends on the project's complexity, the development time, the expertise level of the developers, their geographical location, and the integration of additional technologies. Simple projects could cost a few thousand dollars, while more complex ones may reach tens of thousands. Prices vary, so it's advisable to get multiple quotes for a more accurate estimate tailored to your specific requirements.
Is Django REST Framework easy for web development?
Django REST framework (DRF) is convenient in many ways and offers a number of advantages, such as excellent usability due to web-browsable API, authentication policies that include packages for OAuth1 and OAuth2, serialization that supports both ORM and non-ORM data sources. Also, it is customizable all the way down, has extensive documentation and great community support.
How to control the process of creating a REST API in Python Django?
This can be done using test-driven development (TDD), which is an approach that focuses on writing tests before you start implementing the business logic of your application. This has many benefits, including fast feedback and detailed specification, reduced time spent on reworking and time spent in the debugger, shorter development time to market, SOLID code, and others. TDD tells you whether your last change (or refactoring) broke previously working code. Also, it forces radical simplification of the code, as it should only be written in response to the requirements of the tests.
Can I use Django REST Framework for both small and large-scale projects?
Absolutely, you can use DRF for both small and large-scale projects. It is highly scalable and flexible, making it suitable for projects of any size. Its modularity allows it to be as simple or as complex as needed, catering to a range of project requirements. For smaller projects, it can streamline development and for larger, more complex projects, it can handle high volumes of data and traffic, providing robust and efficient solutions.
Are there any security considerations when developing APIs with Django REST Framework?
Yes, security is crucial when using Django REST Framework. Ensure proper Authentication and Authorization, use HTTPS for secure data transmission, validate and sanitize inputs, implement throttling, and define clear CORS policies. Regularly update the framework and its dependencies and conduct security audits to identify and address potential vulnerabilities.
How does Django REST Framework handle data serialization?
Django REST Framework handles data serialization using serializers that allow complex data types, such as Django models, to be converted to Python data types. The serializers in DRF serve as a bridge between complex querysets and the native Python datatypes, allowing for easy rendering into JSON or XML format for API consumption.

Have an idea? Let's discuss!

Contact Us
Rate this article!
14 ratings, average: 3.64 out of 5
Very bad
Very good
Subscribe us

Latest articles right in
your inbox

Thanks for
We've sent a confirmation email to your inbox.

Subscribe to our newsletter

Thanks for joining us! 💚

Your email address *
By clicking “Subscribe” I allow Django Stars process my data for marketing purposes, including sending emails. To learn more about how we use your data, read our Privacy Policy .
We’ll let you know, when we got something for you.