Tutorial: “Django MongoDB RestAPIs CRUD Example – using Django Rest Framework + Djongo + Atlas MongoDB”
In the tutorial, I introduce how to create a ‘Django MongoDB RestAPIs CRUD Example’ using Django Rest Framework and Djongo with details explanation and running coding:
– I draw overview diagram architecture and explain details the flow of code and main blocks of Django project.
– I guide step by step how to setup and implement the Django project with Django Rest Framework and MongoDB database.
– I create a testsuite with a number of integrative testcases with CRUD RestAPI requests from rest-client Postman to Django Server and save/retrieve data to MongoDB database.
- Django MongoDB RestAPIs CRUD Examples with Django Rest Framework
- Practice – Implement Django MongoDB CRUD RestAPIs with Django Rest Framework + Djongo
- Create a Django project
- Create a Django Application
- Create a Django Data model
- Serialize Data Model
- Setup MongoDB Database Configuration
- Migrate Data Model to MongoDB
- Configure Django Admin Page
- Testing Django Admin Page
- Implement Django CRUD Views – Post/Get/Put/Delete requests
- Configure Django CRUD RestAPI URLs
- Integrative Testing – Django + MongoDB CRUD RestAPIs
- Sourcecode
- Further Reading
Django MongoDB RestAPIs CRUD Examples with Django Rest Framework
Django Framework
Django is an extremely popular and fully featured server-side web framework, written in Python. Django helps eliminate repetitive tasks making the development process an easy and time saving experience. Some well known sites that use Django include Instagram, Disqus, Washington Times, Bitbucket and Mozilla.
Advantages of Django:
- Object-Relational Mapping (ORM) Support – Django provides a bridge between the data model and the database engine,
- Administration GUI − Django provides a nice ready-to-use user interface for administrative activities.
- Development Environment − Django comes with a lightweight web server to facilitate end-to-end application development and testing.
Django supports the Model-View-Template (MVT) pattern.

Django takes care of the Controller part to control the interactions between the Model and View, leaving us with the template. The template is a HTML file mixed with Django Template Language (DTL).
Diagram Architecture of Django RestAPIs Workflow
Here is the diagram architecture of Django MongoDB RestAPIs CRUD Example:

– Django Application interacts with MongoDB database via Model layers.
– The Django Views are simply Python functions that take web requests and return web responses.
– Django URLs are used to mapping each request with the corresponding views.
Project Struture – Django + Django Rest Framework + MongoDB

The Django RestAPIs project includes 2 folders:
djangoLoiZenAiRestAPIs
is a main Django project foldercustomers
is an Django user-created application folder
Practice – Implement Django MongoDB CRUD RestAPIs with Django Rest Framework + Djongo
To prepare an environment for development, you need to install both Python, Django and a MongoDB database.
– You can check python installed by cmd: python --version
C:\Users\USER>python --version
Python 3.8.3
– You can test your Django installation by running this command:
$ django-admin.py --version
C:\Users\USER>django-admin.py --version
3.0.8
Create a Django project
- In Django, every web application you want to create is called a project
- And a project is a sum of applications.
- An application is a set of code files relying on the MVT pattern.
– Open a cmd and type the below command to create a djangoLoiZenAiRestAPIs
project:
$ django-admin startproject djangoLoiZenAiRestAPIs
Now the project folder djangoLoiZenAiRestAPIs
is created with the following structure:
djangoLoiZenAiRestAPIs/
manage.py
djangoLoiZenAiRestAPIs/
__init__.py
settings.py
urls.py
wsgi.py
manage.py
is used to interact with your project via command line (start the development server, sync db…).__init__.py
is a python file that treats this folder as package.settings.py
is a project settings file.urls.py
defines all url links of your project and the function to callwsgi.py
is used when you deploy your project over WSGI
All setting of the Django project is in file djangoLoiZenAiRestAPIs/settings.py
.
Check a debug option:
DEBUG = True
This option sets your project is in debug mode or not. Debug mode gives you more information about your project’s error. In the production live build, Never set it to ‘True’.
Install Django REST framework
Django REST framework works on top of Django and helps us to build RESTful Web Services flexibly. To install this package, run command:
pip install djangorestframework
Create a Django Application
As mention in above session, a Django project has a set of many applications. Each application is implemented with a specific purpose and can be reused into another project.
For creating a Customer
application, we go to the project folder djangoLoiZenAiRestAPIs
. Start the cmd:
$ python manage.py startapp customers
Django will create a “customers” folder with the application structure as below:
customers/
__init__.py
admin.py
models.py
tests.py
views.py
__init__.py
is used by python to handle this folder as a package.admin.py
is used to hepl us modify the app in the admin interface.models.py
is place to store all application models.tests.py
is a place to write unit tests.views.py
is where to implement application views.
Open customers/apps.py
, we can see CustomersConfig
class (subclass of the django.apps.AppConfig
) that represents our Django app and its configuration:
from django.apps import AppConfig
class CustomersConfig(AppConfig):
name = 'customers'
We need to register our customes
application with our Django project djangoLoiZenAiRestAPIs
by updating INSTALLED_APPS
tuple in the settings.py
file of Django project:
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
# Django REST framework
'rest_framework',
# Customers application
'customers.apps.CustomersConfig',
]
Create a Django Data model
Djongo is a Django-MongoDB connector made by Nesdis. This connector is very easy to use because it supports all django contrib libraries. Using Djongo, all we need to do is setting up and changing the models base import, no need to worry about changing serializers, views, and all other modules.
To use Djongo, make sure you have Python 3.6 or higher and MongoDB 3.4 or higher installed (if we need to use nested queries, then we need MongoDB 3.6 or higher) and start to make our projects.
To set up the environment for Djongo, you need to install the package:
pip install djongo
A model class represents table or collection in our DB. Models are defined in the customers/models.py
:
from djongo import models
class Customer(models.Model):
firstname = models.CharField(max_length=70, blank=False, default='')
lastname = models.CharField(max_length=70, blank=False, default='')
age = models.IntegerField(blank=False, default=1)
address = models.CharField(max_length=70, blank=False, default='')
copyrightby = models.CharField(max_length=70, blank=False, default='')
All Django models must inherit from djongo.models.Model
. Customer
class has 5 attributes (4 CharField
and 1 Integer
), those will be the table fields.
Serialize Data Model
For serialization Python model object to JSON and deserialization Python object from JSON, We create a Serializer class for Customer instances:
– The CustomerSerializer
class will inherit from rest_framework.serializers.ModelSerializer
superclass.
– ModelSerializer
class automatically populates a set of default fields and default validators, we only need to specify the model class.
Now, under customers package, create serializers.py
file:
from rest_framework import serializers
from customers.models import Customer
class CustomerSerializer(serializers.ModelSerializer):
class Meta:
model = Customer
fields = ('id',
'firstname',
'lastname',
'age',
'address',
'copyrightby')
Meta inner class declares 2 attributes:
model
specifies the model related to the serializerfields
specifies a tuple of field names that we want to include in the serialization
Setup MongoDB Database Configuration
Before editing your Django project’s settings.py
file, it is important that you install dnspython
. DNSPython is used to connect to the Mongodb+srv:// URI.
pip install dnspython
– Configure again the database tuple in settings.py
file:
DATABASES = {
'default': {
'ENGINE': 'djongo',
"CLIENT": {
"name": 'loizenjavadb',
"host": 'mongodb+srv://loizenjava:loizenjava@cluster0.gmd7e.mongodb.net/loizenjavadb?retryWrites=true&w=majority',
"username": 'loizenjava',
"password": 'loizenjava',
"authMechanism": "SCRAM-SHA-1"
}
}
}
Migrate Data Model to MongoDB
Run following Python script:
python manage.py makemigrations customers
We can see output text:
Migrations for 'customers':
customers\migrations\0001_initial.py
- Create model Customer
It indicates that the customers/migrations/0001_initial.py
file includes code to create Customer
data model:
# Generated by Django 3.0.8 on 2020-07-15 15:43
from django.db import migrations, models
class Migration(migrations.Migration):
initial = True
dependencies = [
]
operations = [
migrations.CreateModel(
name='Customer',
fields=[
('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('firstname', models.CharField(default='', max_length=70)),
('lastname', models.CharField(default='', max_length=70)),
('age', models.IntegerField(default=1)),
('address', models.CharField(default='', max_length=70)),
('copyrightby', models.CharField(default='', max_length=70)),
],
),
]
The generated code defines a subclass of the django.db.migrations.Migration
. It has an operation for creating Customer
model table. Call to migrations.CreateModel()
method will create a table that allows the underlying database to persist the model.
Run the following Python script to apply the generated migration:
python manage.py migrate customers
The output text:
Operations to perform:
Apply all migrations: customers
Running migrations:
Applying customers.0001_initial... OK
Check MongoDB database, now we can see that a table for Customer
model was generated and it’s named customers_customer
:

Configure Django Admin Page
Django provides a ready-to-use user interface for administrative activities. To have it working you need to make sure some modules are imported in the INSTALLED_APPS
and MIDDLEWARE_CLASSES
tuples of the djangoLoiZenAiRestAPIs/settings.py
file.
– INSTALLED_APPS
make sure you have:
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
# Django REST framework
'rest_framework',
# Customers application
'customers.apps.CustomersConfig',
# CORSq
'corsheaders',
]
– MIDDLEWARE_CLASSES:
MIDDLEWARE = [
'django.middleware.security.SecurityMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.common.CommonMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.clickjacking.XFrameOptionsMiddleware',
# CORS
'corsheaders.middleware.CorsMiddleware',
'django.middleware.common.CommonMiddleware',
]
Before running Django server to access the Admin page, we need to initiate the database:
$ python manage.py migrate
Check MongoDB database collections:

Use the below command to create a super-user to login Admin page:
$ python manage.py createsuperuser
Register admin URL in djangoLoiZenAiRestAPIs/urls.py
file:
from django.contrib import admin
from django.urls import path
from django.conf.urls import url, include
urlpatterns = [
path('admin/', admin.site.urls),
]
Register Customer
model in ./customers/admin.py
file:
from django.contrib import admin
# Register your models here.
from customers.models import Customer
# Register your models here.
admin.site.register(Customer)
Testing Django Admin Page
Launch Django server by cmd:
python manage.py runserver
Go to Admin page by URL link http://localhost:8000/admin/
:

Site Administration has 2 parts:
- AUTHENTICATION AND AUTHORIZATION
- CUSTOMERS
– Authentication and Authorization has Groups
and Users
pages, where we can add, modify, delete, update a specific user.

– Customers is a place to manipulate (create, get, update, delete) all entities of the Customers application.


Implement Django CRUD Views – Post/Get/Put/Delete requests
Django “view” is simply a Python function that takes a web request and returns a web response. This response can be the HTML contents of a Web page, or a redirect, or a 404 error, or an XML document, or an image … In the tutorial, we implement Django views that return JSON responses.

We create 3 Python function for Django views:
def customer_list(request)
is used to POST a Customer entity, GET/DELETE all Customer entities per a requestdef customer_detail(request, pk)
is used to GET/PUT/DELETE a Customer viaid
keydef customer_list_age(request, age)
is used to filter all Customers byage
via a GET request
Django Post/Get/Delete requests
In the ./customers/views.py
file, I implements a Python function def customer_list(request)
for POST/GET/DELETE Customer entities
@api_view(['GET', 'POST', 'DELETE'])
def customer_list(request)
Django implement Post request
Here is a list of 4 steps we do to handle a Django POST request:
- Parsing a body request then serializing it to transform the JSON data to a Python Object
customer_data = JSONParser().parse(request) customer_serializer = CustomerSerializer(data=customer_data)
- Save the serializing object to database:
customer_serializer.save()
- Return a JsonResponse object to a client with a status code
JsonResponse(response, status=status.HTTP_201_CREATED)
- If having any error or exception, return the JSON error object to client
JsonResponse(error, status=status.HTTP_400_BAD_REQUEST)
or
JsonResponse(exceptionError, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
– Coding Example:
if request.method == 'POST':
try:
customer_data = JSONParser().parse(request)
customer_serializer = CustomerSerializer(data=customer_data)
if customer_serializer.is_valid():
customer_serializer.save()
print(customer_serializer.data)
response = {
'message': "Successfully Upload a Customer with id = %d" % customer_serializer.data.get('id'),
'customers': [customer_serializer.data],
'error': ""
}
return JsonResponse(response, status=status.HTTP_201_CREATED)
else:
error = {
'message':"Can Not upload successfully!",
'customers':"[]",
'error': customer_serializer.errors
}
return JsonResponse(error, status=status.HTTP_400_BAD_REQUEST)
except:
exceptionError = {
'message': "Can Not upload successfully!",
'customers': "[]",
'error': "Having an exception!"
}
return JsonResponse(exceptionError, status=status.HTTP_500_INTERNAL_SERVER_ERROR);
Django implement Get request
For getting all Customer entities from database with Django GET request, we do a list of 4 steps as following:
- Get all Customer’ entities via Customer model class
- Serialize a List of Customer Objects
- Return a
JsonResponse
object with Python dictionary body and http status code
JsonResponse(response, status=status.HTTP_200_OK);
- If having any error or exception, just return a
JsonResponse
object with a building body for errors and a http status error code:
JsonResponse(error, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
if request.method == 'GET':
try:
customers = Customer.objects.all()
customers_serializer = CustomerSerializer(customers, many=True)
response = {
'message': "Get all Customers'Infos Successfully",
'customers': customers_serializer.data,
'error': ""
}
return JsonResponse(response, status=status.HTTP_200_OK);
except:
error = {
'message': "Fail! -> can NOT get all the customers List. Please check again!",
'customers': "[]",
'error': "Error"
}
return JsonResponse(error, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
Django implement Delete request
For deleting all entities from database, we just use a .all().delete()
API function of django.db.models.Model
class.
– Details example:
elif request.method == 'DELETE':
try:
Customer.objects.all().delete()
return HttpResponse(status=status.HTTP_204_NO_CONTENT)
except:
exceptionError = {
'message': "Can Not Deleted successfully!",
'customers': "[]",
'error': "Having an exception!"
}
return JsonResponse(exceptionError, status=status.HTTP_500_INTERNAL_SERVER_ERROR);
Django Put request
In ./customers/views.py
file, We define a view function customer_detail
to do a PUT/GET/DELETE a Customer entity with a given id:
@api_view(['GET', 'PUT', 'DELETE'])
def customer_detail(request, pk)
For PUT/GET/DELETE a database entity with a given id
, firstly we need to check the existing of an entity with the id
. If having an DoesNotExist
exception throws, we stop processing the request and return a JsonResponse
object with a body is an exception’s error and a http status code NOT_FOUND
:
try:
customer = Customer.objects.get(pk=pk)
except Customer.DoesNotExist:
exceptionError = {
'message': "Not found a Customer with id = %s!" % pk,
'customers': "[]",
'error': "404 Code - Not Found!"
}
return JsonResponse(exceptionError, status=status.HTTP_404_NOT_FOUND)
For handing a PUT request, we do a list actions with 4 steps:
- Parsing the request’s body object
customer_data = JSONParser().parse(request)
- De-serialize the above parsing data:
customer_serializer = CustomerSerializer(customer, data=customer_data)
- Store the object to database by
.save()
API function:
customer_serializer.save()
- Return a
JsonResponse
object with user-defined response:response = { 'message': "Successfully Update a Customer with id = %s" % pk, 'customers': [customer_serializer.data], 'error': "" } return JsonResponse(response)
- If having any exception being throwed, we need to handle it and return an error with 404 status code:
return JsonResponse(response, status=status.HTTP_400_BAD_REQUEST)
try:
customer_data = JSONParser().parse(request)
customer_serializer = CustomerSerializer(customer, data=customer_data)
if customer_serializer.is_valid():
customer_serializer.save()
response = {
'message': "Successfully Update a Customer with id = %s" % pk,
'customers': [customer_serializer.data],
'error': ""
}
return JsonResponse(response)
response = {
'message': "Fail to Update a Customer with id = %s" % pk,
'customers': [customer_serializer.data],
'error': customer_serializer.errors
}
return JsonResponse(response, status=status.HTTP_400_BAD_REQUEST)
Here is the remain code in the view function def customer_detail(request, pk)
for GET and DELETE request with a given id:
if request.method == 'GET':
customer_serializer = CustomerSerializer(customer)
response = {
'message': "Successfully get a Customer with id = %s" % pk,
'customers': [customer_serializer.data],
'error': ""
}
return JsonResponse(response, status=status.HTTP_200_OK);
...
elif request.method == 'DELETE':
print("Deleting a Customer with id=%s"%pk)
customer.delete()
customer_serializer = CustomerSerializer(customer)
response = {
'message': "Successfully Delete a Customer with id = %s" % pk,
'customers': [customer_serializer.data],
'error': ""
}
return JsonResponse(response)
Django Filter request
Now We continue define a Django GET RestAPI to filter all Customer entities with a given age
as below code:
@api_view(['GET'])
def customer_list_age(request, age):
try:
customers = Customer.objects.filter(age=age)
if request.method == 'GET':
customers_serializer = CustomerSerializer(customers, many=True)
response = {
'message': "Successfully filter all Customers with age = %s" % age,
'customers': customers_serializer.data,
'error': ""
}
return JsonResponse(response, safe=False)
# In order to serialize objects, we must set 'safe=False'
except:
exceptionError = {
'message': "Fail to get a Customer with age = %s" % age ,
'customers': "[]",
'error': "Raise an Exception!"
}
return JsonResponse(exceptionError, status=status.HTTP_500_INTERNAL_SERVER_ERROR);
We had used a function API filter(**kwargs)
to filter all Customer entities from PostgreSQL database that match the given lookup parameters customers_serializer = CustomerSerializer(customers, many=True)
.
Configure Django CRUD RestAPI URLs
We define a set of Rest URL for Customers Application in file ./customers/urls.py
:
from django.conf.urls import url
from customers import views
urlpatterns = [
url(r'^customers/$', views.customer_list),
url(r'^customers/(?P<pk>[0-9]+)$', views.customer_detail),
url(r'^customers/age/(?P<age>[0-9]+)/$', views.customer_list_age),
]
We need include the Customer Application’s URL file to project’s urls.py
file:
from django.contrib import admin
from django.urls import path
from django.conf.urls import url, include
urlpatterns = [
url(r'^', include('customers.urls')),
path('admin/', admin.site.urls),
]
Integrative Testing – Django + MongoDB CRUD RestAPIs
Testcase 1 – Django Post request to MongoDB

– Check MongoDB database:

Testcase 2 – Django Get request: retrieve all data from MongoDB

Testcase 3 – Django Put request: update a data from MongoDB

Testcase 4 – Django Filter RestAPI with a Get request

Testcase 5 – Django Delete request: remove a record from MongoDB

– Checking MongoDB after doing CRUD operations:

Sourcecode
Here is the clearly sourcecode of Django MongoDB RestAPIs CRUD Example with Django Rest Framework ORM:
– GITHUB Sourcecode:
Django CRUD RestAPIs MongoDB Atlas
Thanks for the tutorial, very clear. How to create sub-document from model?