Building an Image Upload API with Django Rest Framework – DRF

In today’s digital era, handling images is a common requirement for many web applications. Whether you’re building a social media platform, an e-commerce site, or a blogging platform, enabling users to upload images is often a crucial feature. In this blog post, we’ll explore how to create a simple Image Upload API using Django Rest Framework (DRF), a powerful toolkit for building web APIs in Django.


Before diving into the implementation, make sure you have the following installed:

  • Python (preferably Python 3.x)
  • Django
  • Django Rest Framework

You can install Django and DRF using pip, Python’s package installer:

pip install django djangorestframework

Setting Up the Project

Let’s start by creating a new Django project and a Django app within it.

django-admin startproject image_upload_api_project
cd image_upload_api_project
python startapp imageupload

Next, add imageupload to the list of installed apps in


Model Creation

We’ll create a simple model to represent our images. Open imageupload/ and define the following model:

from django.db import models

class Image(models.Model):
    title = models.CharField(max_length=100)
    image = models.ImageField(upload_to='images/')

    def __str__(self):
        return self.title

This model consists of two fields: title, which is a character field to store the title of the image, and image, which is an ImageField to store the actual image file.

After defining the model, run the migrations to create the necessary database tables:

python makemigrations
python migrate


Now, let’s create a serializer for our Image model. Serializers in DRF allow complex data such as querysets and model instances to be converted to native Python datatypes that can then be easily rendered into JSON, XML, or other content types.

Create a new file inside the imageupload app directory and define the serializer:

from rest_framework import serializers
from .models import Image

class ImageSerializer(serializers.ModelSerializer):
    class Meta:
        model = Image
        fields = '__all__'


Next, we’ll create views to handle the image upload functionality. Open imageupload/ and define the following views:

from rest_framework import status
from rest_framework.decorators import api_view
from rest_framework.response import Response
from .models import Image
from .serializers import ImageSerializer

def upload_image(request):
    serializer = ImageSerializer(
    if serializer.is_valid():
        return Response(, status=status.HTTP_201_CREATED)
    return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

Here, we define a single view upload_image that accepts POST requests. It serializes the incoming data using our ImageSerializer and saves the image if the data is valid.


Finally, let’s wire up our views to URLs. Open image_upload_api_project/ and define the following URL configuration:

from django.urls import path
from imageupload.views import upload_image

urlpatterns = [
    path('upload/', upload_image, name='upload_image'),

Testing the API

Now that our API is set up, we can test it using a tool like Postman or by writing a simple client application. Send a POST request to the /upload/ endpoint with the image file in the request body, and you should receive a response containing the uploaded image data if successful.

Testing your Image Upload API can be done using various methods. Here, I’ll outline a couple of approaches: manual testing using tools like Postman and automated testing using Django’s test framework.

Manual Testing with Postman:

  1. Install Postman: If you haven’t already, download and install Postman, a popular API client that allows you to easily test API endpoints.
  2. Start the Django Development Server: Ensure your Django development server is running by executing python runserver.
  3. Create a New Request in Postman:
    • Open Postman and create a new request.
    • Set the request type to POST.
    • Enter the URL of your API endpoint (http://localhost:8000/upload/ if running locally).
    • In the request body, select form-data.
    • Add a key-value pair where the key is image (matching the name of the field in your API) and the value is an image file.
  1. Send the Request: Click on the “Send” button to send the request to your API endpoint.
  2. Verify the Response: Postman will display the response from your API. If the upload was successful, you should receive a response containing the uploaded image data.

Automated Testing with Django’s Test Framework:

  • Writing Test Cases: Create test cases to verify the functionality of your API endpoints. You can create a test file (e.g., within your Django app directory (imageupload/ and define test classes and methods.
  • Example Test Case: Here’s an example test case using Django’s TestCase class:
from django.test import TestCase
from django.urls import reverse
from rest_framework import status
from rest_framework.test import APIClient

class ImageUploadAPITest(TestCase):
    def setUp(self):
        self.client = APIClient()

    def test_upload_image(self):
        url = reverse('upload_image')
        with open('path/to/your/image.jpg', 'rb') as image_file:
            response =, {'image': image_file}, format='multipart')
        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
  • Run Tests: Execute your test cases using Django’s management command:
python test

Django will run your test cases and provide feedback on whether they passed or failed.

By combining manual testing with tools like Postman and automated testing with Django’s test framework, you can ensure that your Image Upload API works as expected under various scenarios and edge cases. This helps maintain the reliability and stability of your API as you continue to develop and evolve your application.


In this tutorial, we’ve covered the basics of building an Image Upload API using Django Rest Framework. We created a simple Django project, defined a model to store images, implemented a serializer to handle serialization/deserialization, wrote views to handle image uploads, and configured URLs to route requests appropriately. With this foundation, you can expand upon the API by adding features like authentication, image resizing, or integrating it into a larger application.

You can find this tutorial on GitHub.