The app accepts both.

Behind the scenes, each request passed the credit check. But the application accepted more work than your balance could pay for. What you just experienced is called a race condition.

For a developer, this raises two questions:

• How can both requests pass the check when there's only enough credit for one?

• How do you prevent them from spending the same credit?

In this guide, we’ll build a small Django credit system to explore those questions. We’ll reproduce the bug, fix it with database transactions and row locks, and test what happens when two requests compete for the last credit.

What We’ll Cover

• Concurrency, race conditions, and the credit check

• How to set up the Django project

• How to reproduce the race condition

• How to protect the balance

• How to accept and test image requests

• Common mistakes and next steps

Who This Guide Is For

This guide is for developers who understand basic Django but are new to concurrency.

Familiarity with models, migrations, and views will help you follow the examples. You’ll need Python 3.12 and Docker with Compose for the setup shown here. We’ll use Django 5.2, Django REST Framework 3.16, and PostgreSQL 17 because SQLite doesn't implement the row lock we’ll use.

I'll explain the concurrency concepts before we apply them to the code.

Image generation will be simulated throughout the tutorial.

Our API will accept a prompt and return a simulated result. You won't need an AI provider account or a paid API key. This keeps the exercise focused on the credit decision and its database changes.

You can follow the entire example without paying for an image request.

What Concurrency and Race Conditions Mean

What Is Concurrency?

Concurrency refers to when two or more tasks make progress during overlapping periods of time.

For example, a server can start processing Request B while Request A waits for a database response. Their instructions don't have to execute at the same instant. An event loop can switch between tasks while one waits, which is one way Python supports concurrent work.

The important detail is that another operation can make progress before the first one finishes.

What Is a Race Condition?

A race condition is a flaw where the correctness of a result depends on the timing or order of concurrent operations.

It can occur when operations share data, and the application doesn't coordinate their access adequately. Each operation may appear correct on its own, yet one can act on information another has already changed. A different execution order can then produce a different, incorrect outcome.

Concurrency creates the opportunity for overlap, and a race condition is a bug that can arise from how the application handles that overlap.

Where Else Can Race Conditions Happen?

Race conditions can affect counters, user accounts, background jobs, and the results displayed in a browser.

The participants can be two requests from one person, two different users, or automated tasks with no user action at all. The shared resource can be a database row, a file, an in-memory value, or the current state of a page. The examples below illustrate several ways the order can matter.

Look for operations that share state and can interfere before either finishes.

A View Counter Loses an Update

Imagine two requests try to increase a post’s view count from 100.

Both read 100 before either saves a change. Each adds one and writes 101. The counter should have reached 102, so one update disappears.

This is a lost update, and no purchase or limited stock is involved.

Two Signups Claim the Same Username

A registration form can race if it relies only on a preliminary username check.

Two requests check the same name, and both find it available. Each then attempts to create an account with that name. Without a database uniqueness rule, the application may create duplicate usernames.

The protection here includes enforcing uniqueness in the database rather than trusting the earlier check.

Two Workers Pick the Same Job

Background workers can accidentally process the same pending job.

Both workers read its status before either claims it. Each decides the job is available and begins the work. The application may then send a notification twice or generate the same report twice.

A job-claim mechanism needs to coordinate ownership before the work begins.

An Older Search Response Replaces a Newer One

A browser can display the wrong search results because responses arrive out of order.

You type “Django”, then change the search to “Django transactions” before the first response returns. The second response arrives first and displays the results you now want. If the first response arrives later and replaces them without a check, the page shows results for the old query.

A request identifier or stale-response check addresses this case, so a database row lock wouldn't be the relevant fix.

How the Credit Check Can Fail

First, let’s define the rule for our example from the beginning of this tutorial: each image request costs one credit. Credits represent the app’s usage allowance. They're separate from the tokens a model processes.

This is a rule we’re choosing for this tutorial. If an account starts with ten credits, nine accepted requests leave enough for one more.

To accept a request, the backend must:

1. Read the account’s balance.

2. Check whether at least one credit remains.

3. Deduct a credit and save the balance.

4. Record the accepted request.

When you test one request at a time, this process can appear correct. The first request saves a balance of zero. The next reads zero and stops.

The next step is to examine the same operations when their execution overlaps.

What Happens When Two Requests Overlap

Suppose Request A reads the account and finds one credit. Before it updates the database, Request B reads the same account. It also finds one credit.

Each request now has its own copy of the balance. Both pass the check, and both calculate 1 - 1 = 0. Request A saves zero and records a generation. Request B then saves zero and records another generation.

The final balance is zero, but the application accepted two requests. A check for negative balances would miss this particular failure.

The mistake is trusting a value after another request has had an opportunity to change it. To see this in practice, we’ll first build the version with that mistake.

How to Set Up the Django Project

Create a project directory and a virtual environment. The activation command below is for Linux and macOS:

mkdir django-credit-demo
cd django-credit-demo
python3.12 -m venv .venv
source .venv/bin/activate

These commands give our example its own directory and Python environment.

mkdir creates the directory, and cd moves you into it. The venv command creates an isolated environment named .venv. The source command activates it so subsequent package installations belong to this project.

Keep this environment active while you run the commands below.

On Windows, use py -3.12 -m venv .venv to create the environment and .venv\Scripts\Activate.ps1 to activate it in PowerShell.

Create requirements.txt:

Django>=5.2,<5.3
djangorestframework>=3.16,<3.17
psycopg[binary]>=3.2,<3.3

This file lists the three packages the project needs.

Django supplies the models and database tools, while Django REST Framework handles the endpoint. Psycopg provides the PostgreSQL connection, and [binary] requests its prebuilt implementation. Each version range allows updates within the chosen release series while excluding the next series.

Using one requirements file makes the dependencies explicit for anyone who follows the guide.

Install the packages, create the project, and add an app named credits:

python -m pip install -r requirements.txt
python -m django startproject config .
python manage.py startapp credits

These commands install the dependencies and create the application structure.

pip install -r reads the package list from requirements.txt. The startproject command creates the config package and manage.py, with the final dot selecting the current directory. The startapp command creates the credits package where our models, service functions, views, and tests will live.

We now have a Django project ready to connect to a database.

Start PostgreSQL

Create compose.yaml beside manage.py:

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_DB: credit_demo
      POSTGRES_USER: credit_demo
      POSTGRES_PASSWORD: local-demo-only
    ports:
      - "127.0.0.1:5433:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U credit_demo -d credit_demo"]
      interval: 2s
      timeout: 5s
      retries: 15

This configuration describes a PostgreSQL container for local development.

image chooses PostgreSQL 17, and the environment values set up the database and local credentials. The port mapping exposes the database only on your computer’s loopback address at port 5433. The health check runs pg_isready every two seconds, allows five seconds per check, and permits fifteen retries before marking the container unhealthy.

Django will use these same connection details in its settings.

Start it with:

docker compose up -d --wait

This command starts the database defined in compose.yaml.

up creates and starts the service. The -d flag lets it run in the background so you can continue using the terminal. The --wait flag waits for the service to become healthy according to the health check.

Keep the database container running throughout the tutorial.

Configure Django

Replace config/settings.py with this minimal configuration:

import os

SECRET_KEY = "local-tutorial-only-do-not-use-in-production"
DEBUG = True
ALLOWED_HOSTS = ["localhost", "127.0.0.1", "testserver"]
INSTALLED_APPS = [
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "rest_framework",
    "credits",
]
MIDDLEWARE = []
ROOT_URLCONF = "config.urls"
DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
USE_TZ = True
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ.get("DB_NAME", "credit_demo"),
        "USER": os.environ.get("DB_USER", "credit_demo"),
        "PASSWORD": os.environ.get("DB_PASSWORD", "local-demo-only"),
        "HOST": os.environ.get("DB_HOST", "127.0.0.1"),
        "PORT": os.environ.get("DB_PORT", "5433"),
        "OPTIONS": {"options": "-c lock_timeout=5000 -c statement_timeout=10000"},
    }
}
REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework.authentication.BasicAuthentication",
    ],
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.IsAuthenticated",
    ],
}

This settings file connects the parts of our small application.

INSTALLED_APPS enables Django’s user support, Django REST Framework, and our credits app. ROOT_URLCONF points to the route definitions, while DEFAULT_AUTO_FIELD and USE_TZ configure automatic identifiers and timezone-aware dates. The empty MIDDLEWARE list keeps this API example minimal, and ALLOWED_HOSTS accepts the local addresses and test client host.

These settings are tailored to this tutorial’s endpoint.

The DATABASES section tells Django how to reach PostgreSQL.

ENGINE selects the PostgreSQL backend. Each os.environ.get() reads an optional environment variable and falls back to the matching container value. The options set a five-second lock timeout and a ten-second statement timeout, so a stalled operation raises an error instead of waiting indefinitely.

A timeout is an error path, and this small endpoint doesn't provide a custom response for it.

The REST_FRAMEWORK section requires an authenticated user.

BasicAuthentication reads credentials supplied with the request. IsAuthenticated rejects anonymous callers before the view accepts their prompt. The sample secret key and DEBUG = True are local development settings.

For deployment, configure production secrets, appropriate authentication, and encrypted connections.

Replace config/urls.py with an empty route list for now. We’ll add the endpoint after we fix the credit logic:

urlpatterns = []

This empty list temporarily gives Django no application routes.

Django reads urlpatterns from the module named in ROOT_URLCONF. We removed the generated admin route because this minimal configuration doesn't enable the admin app. Database commands can still run before an endpoint exists.

We’ll replace this list when the protected view is ready.

Create the Models

Add these models to credits/models.py:

from django.conf import settings
from django.db import models


class CreditAccount(models.Model):
    user = models.OneToOneField(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
    balance = models.PositiveIntegerField(default=0)


class Generation(models.Model):
    account = models.ForeignKey(CreditAccount, on_delete=models.CASCADE)
    prompt = models.CharField(max_length=500)
    status = models.CharField(max_length=20, default="reserved")
    created_at = models.DateTimeField(auto_now_add=True)

CreditAccount stores the balance associated with a user.

settings.AUTH_USER_MODEL refers to the project’s configured user model. The OneToOneField allows at most one account per user, and on_delete=models.CASCADE tells Django to remove the account when it deletes that user. PositiveIntegerField(default=0) stores a nonnegative whole-number balance with an initial value of zero.

The balance field represents our allowance, but its type alone can't enforce one generation per credit.

Generation stores the work the application has accepted.

The foreign key links each record to its paying account and allows an account to have many generations. prompt holds up to 500 characters, while created_at records when the row is created. status starts as reserved, meaning our service has recorded the request but hasn't completed the simulated image work.

Keeping a generation record lets us check what the deducted credit actually paid for.

Create and apply the migrations:

python manage.py makemigrations credits
python manage.py migrate

These commands turn the model definitions into database tables.

makemigrations credits creates migration files describing the model changes. migrate applies pending migrations, including Django’s user tables and our two new tables. The connection comes from the database settings we just configured.

The database is now ready to store an account and its generation requests.

How to Reproduce the Race Condition

Create credits/services.py and add this deliberately unsafe function:

from .models import CreditAccount, Generation


class InsufficientCredits(Exception):
    pass


def reserve_generation_unsafe(user_id, prompt):
    account = CreditAccount.objects.get(user_id=user_id)

    if account.balance < 1:
        raise InsufficientCredits

    account.balance -= 1
    account.save(update_fields=["balance"])

    return Generation.objects.create(account=account, prompt=prompt)

This function implements the credit check without concurrency protection.

objects.get() retrieves the account foruser_id, and raise InsufficientCredits stops the function if the balance is below one. The subtraction changes the Python object, then save(update_fields=["balance"]) writes that value to the database. Finally, Generation.objects.create() inserts the accepted request and returns its model object.

The read and write remain separate operations, so another request can act between them.

InsufficientCredits gives the caller a specific failure to handle.

It's a custom exception class derived from Python’s Exception. The pass statement means we don't add any behaviour to that class. Later, the view will catch this exception and return a useful response.

Keep the deliberately unsafe function available for comparison, but don't route the endpoint through it.

Make Both Reads Happen Before Either Write

Opening two browser tabs isn't a reliable way to reproduce the bug. One request might finish before the other reads the balance. Instead, we’ll use two Django shells and pause after each has read the account.

Open a terminal in your project directory, activate the virtual environment, and start the shell:

python manage.py shell

This command opens a Python shell with the Django project loaded.

It uses the settings associated with manage.py. You can import the models and query the configured database directly. Each terminal you open provides a separate shell for our experiment.

We’ll use those shells to control the order of the database operations.

Create a fresh user and an account with one credit:

from django.contrib.auth import get_user_model
from credits.models import CreditAccount, Generation

user = get_user_model().objects.create_user(username="race-demo")
CreditAccount.objects.create(user=user, balance=1)

account_a = CreditAccount.objects.get(user__username="race-demo")
print(account_a.balance)

This block prepares the first operation with a balance of one.

get_user_model() retrieves the configured user class, and create_user() inserts our demonstration user. The account creation assigns that user one credit. The lookup uses user__username to follow the user relationship and stores the resulting account object in account_a.

The print should show1. Leave this shell open without updating the account.

In a second terminal, activate the same environment and run python manage.py shell again. Read the account there too:

from credits.models import CreditAccount, Generation

account_b = CreditAccount.objects.get(user__username="race-demo")
print(account_b.balance)

The second shell reads the same database row into a different Python object.

account_b belongs to this shell and is separate from account_a. The first shell hasn't saved a deduction, so this lookup should also return a balance of one. Later changes in the other shell won't automatically refresh this object.

Both operations now have a copy of the credit they intend to spend.

Return to the first shell and run:

if account_a.balance >= 1:
    account_a.balance -= 1
    account_a.save(update_fields=["balance"])
    Generation.objects.create(account=account_a, prompt="A garden")

The first shell now checks and spends its copy of the balance.

The if condition passes because account_a.balance is one. The subtraction changes it to zero, and save() writes zero to the account row. The final line creates a generation for the garden prompt.

Press Enter on a blank line to finish the block before switching terminals.

Then run the corresponding block in the second shell:

if account_b.balance >= 1:
    account_b.balance -= 1
    account_b.save(update_fields=["balance"])
    Generation.objects.create(account=account_b, prompt="A beach")

The second shell makes its decision using the object it loaded earlier.

Its if condition still sees one because we have not refreshed account_b. It subtracts one and saves zero, overwriting the balance with the same value the first operation wrote. It then creates a separate generation for the beach prompt.

The second operation has accepted work using a credit the first operation already spent.

Finally, check the database from the second shell:

account_b.refresh_from_db()
print(account_b.balance)
print(Generation.objects.filter(account=account_b).count())

This block checks the stored result of both operations.

refresh_from_db() reloads the account so the print reflects the database value. The filtered count() counts only generations linked to that account. You should see zero credits and two generation records.

The generation count reveals the failure that the balance alone would hide.

The two shells let us reproduce the unsafe sequence deliberately.

We paused after each read and then allowed both writes. A server can produce the same order when requests overlap, even though it won't do so on every attempt. To repeat the experiment, create a new username and account so previous records don't affect the count.

We can now build protection around the exact gap we observed.

How to Protect the Balance

There are two database concerns in this function. The credit deduction and generation record should succeed together. Competing requests also need a coordinated way to check and update the account.

We’ll address them in that order.

Keep Related Changes in One Transaction

A database transaction groups operations into a unit of work. Django’s transaction.atomic() commits the changes when the block completes successfully and rolls them back if an exception leaves the block.

This matters because the unsafe function saves the balance before it creates the generation record. If record creation fails, the deduction can remain without an accepted generation.

For illustration, wrapping the operations looks like this:

from django.db import transaction


@transaction.atomic
def reserve_generation_atomic_only(user_id, prompt):
    account = CreditAccount.objects.get(user_id=user_id)

    if account.balance < 1:
        raise InsufficientCredits

    account.balance -= 1
    account.save(update_fields=["balance"])

    return Generation.objects.create(account=account, prompt=prompt)

The decorator places the function’s database operations inside an atomic transaction.

from django.db import transaction provides Django’s transaction tools. The function still reads the account, checks the balance, saves the deduction, and creates the generation in that order. If an exception escapes during record creation, the transaction rolls back the deduction too.

This protects the relationship between the deduction and its generation record.

The plain account lookup still leaves the credit check exposed.

PostgreSQL uses Read Committed as its default isolation level. Under it, a plain read inside a transaction doesn't make another transaction wait before reading the row. Both functions can therefore read one credit before either updates it.

We need to coordinate access before making the balance decision.

Lock the Account Before the Balance Check

Row locking is a database mechanism that restricts conflicting operations on selected rows while a transaction holds a lock.

In this example, a row is the stored record for one credit account. A SELECT FOR UPDATE lock makes competing updates and conflicting lock requests wait until the lock is released. Ordinary reads can still proceed, and transactions can work on other account rows.

This lets us protect one account while its balance is checked and changed.

Add from django.db import transaction at the top of credits/services.py. Keep the unsafe function for comparison, then add this protected version:

@transaction.atomic
def reserve_generation(user_id, prompt):
    account = CreditAccount.objects.select_for_update().get(user_id=user_id)

    if account.balance < 1:
        raise InsufficientCredits

    account.balance -= 1
    account.save(update_fields=["balance"])

    return Generation.objects.create(account=account, prompt=prompt)

This function acquires the account’s row lock before it checks the balance.

select_for_update() requests the lock, and .get(user_id=user_id) executes the query for this account inside the transaction. Once it holds the lock, the function checks the balance and raises InsufficientCredits if necessary. Otherwise, it saves the deduction and creates the generation before the transaction completes.

The decision and its database changes now happen while the account is protected.

A competing call to this function must wait at the locking query.

If the first call commits its deduction, the waiting call checks the updated balance under our Read Committed setup. If the first call rolls back, its deduction doesn't remain. Our configured timeout can also stop the wait with an error.

For one credit and a successful first commit, the second call reads zero and rejects the request.

This protection needs to cover every path that spends the balance.

An older function could still read an account without requesting a lock. Its later update would wait while our lock is held, but it could then overwrite the balance using its stale value. Administrative adjustments and background jobs therefore need a safe update strategy, too.

One protected function can't correct an unsafe writer elsewhere.

Keep Image Generation Outside the Transaction

The transaction should cover the credit reservation. A remote image request could take much longer than those database operations, so placing it inside the transaction would keep competing requests waiting unnecessarily.

For our demo, add this function to credits/services.py:

def simulate_generation(generation):
    # No external AI request is made in this tutorial.
    generation.status = "completed"
    generation.save(update_fields=["status"])
    return "Simulated image generation completed."

This function simulates completion of an accepted generation.

It changes the supplied generation object’s status to completed. The save() call persists only that field. The return value is a message, so the function produces no image and makes no external request.

We’ll call it after the reservation function returns.

The call order keeps image work outside the reservation transaction.

With these settings and no enclosing transaction, the reservation commits before the simulation starts. A failure after that point wouldn't automatically restore the credit. A real provider integration needs its own retry or refund policy.

We’ll return to those limits after we test the reservation itself.

How to Accept and Test Image Requests

Now we can connect the protected function to an endpoint. Add this code to credits/views.py:

from rest_framework import serializers, status
from rest_framework.response import Response
from rest_framework.views import APIView
from .models import CreditAccount
from .services import InsufficientCredits, reserve_generation, simulate_generation


class GenerationInput(serializers.Serializer):
    prompt = serializers.CharField(max_length=500)


class GenerateView(APIView):
    def post(self, request):
        serializer = GenerationInput(data=request.data)
        serializer.is_valid(raise_exception=True)
        try:
            generation = reserve_generation(
                request.user.pk, serializer.validated_data["prompt"]
            )
        except CreditAccount.DoesNotExist:
            return Response({"detail": "Credit account not found."}, status=404)
        except InsufficientCredits:
            return Response({"detail": "Not enough credits."}, status=409)

        result = simulate_generation(generation)
        return Response(
            {"id": generation.pk, "status": generation.status, "result": result},
            status=status.HTTP_201_CREATED,
        )

The serializer checks the prompt before the view spends a credit.

GenerationInput declares a required text field with a maximum length of 500 characters. is_valid(raise_exception=True) rejects missing, blank, or invalid input with a validation response. The view then reads the cleaned value from validated_data and passes it with request.user.pk, the authenticated user’s database identifier, to the reservation function.

The client supplies a prompt while the server chooses the account from the authenticated user.

The view translates the reservation outcome into a response.

A missing account produces404, and InsufficientCredits produces 409, our chosen response for the balance conflict. On success, the view calls the simulation after the reservation returns. It sends 201 with the record identifier, completion status, and simulated result.

These branches let the caller distinguish accepted work from a rejected request.

Replace config/urls.py with:

from django.urls import path
from credits.views import GenerateView

urlpatterns = [
    path("api/generate/", GenerateView.as_view()),
]

This route connects the request address to our view.

path() matches the api/generate/ part of the address. GenerateView.as_view() turns the class-based view into a callable Django can dispatch to. The view’s post() method handles a POST request at that route.

The endpoint is now available at /api/generate/ when the server runs.

Try One Request at a Time

Open the Django shell and create a separate user for the endpoint demonstration:

from django.contrib.auth import get_user_model
from credits.models import CreditAccount

user = get_user_model().objects.create_user(
    username="api-demo",
    password="local-example-password",
)
CreditAccount.objects.create(user=user, balance=1)

This block creates a user for the authenticated endpoint example.

create_user() saves the username and hashes the supplied password. CreditAccount.objects.create() gives the new user one credit. A separate username keeps this check independent of the account used in the two-shell experiment.

The credentials below belong only to this local demonstration account.

Exit the shell and start the development server:

python manage.py runserver

This command starts Django’s development server.

With no address argument, it listens at 127.0.0.1:8000. Requests at that address pass through the route configuration we just added. Keep this terminal open while you send the request from another terminal.

This server is for the local demonstration.

In another terminal, send a request:

curl -i -u api-demo:local-example-password \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A garden at sunrise"}' \
  http://127.0.0.1:8000/api/generate/

This command submits a prompt to the endpoint with the demonstration user’s credentials.

-i includes response headers, and -u supplies the username and password for Basic authentication. -H declares JavaScript Object Notation (JSON) as the request body format. -d supplies that body and makes curl send a POST request to the address shown.

The first request should return 201 with the simulated completion result.

Sending the command again checks the account after the first deduction.

The next request should find zero credits. The view should return 409 with "detail": "Not enough credits.". Because we waited between requests, this verifies the ordinary sequence without exercising concurrency.

Next, we’ll test overlapping operations.

Set Up the Automated Tests

Replace credits/tests.py with the following imports and helper class. We’ll add the test methods in the next steps.

from concurrent.futures import ThreadPoolExecutor
from threading import Barrier
from unittest.mock import patch

from django.contrib.auth import get_user_model
from django.db import (
    OperationalError, close_old_connections, connection, connections, transaction,
)
from django.test import TransactionTestCase
from rest_framework.test import APIClient

from .models import CreditAccount, Generation
from .services import InsufficientCredits, reserve_generation, reserve_generation_unsafe


class ConcurrencyTests(TransactionTestCase):
    def setUp(self):
        if connection.vendor != "postgresql":
            self.skipTest("Run these concurrency tests on PostgreSQL.")

        self.user = get_user_model().objects.create_user(username="parallel-reader")
        self.account = CreditAccount.objects.create(user=self.user, balance=1)

    def run_two(self, action):
        def worker():
            close_old_connections()
            try:
                return action()
            finally:
                connections.close_all()

        with ThreadPoolExecutor(max_workers=2) as pool:
            futures = [pool.submit(worker) for _ in range(2)]
            return [future.result(timeout=15) for future in futures]

The test class prepares a fresh account before each concurrency test.

setUp() skips the test when the connection isn't PostgreSQL. It then creates a user and an account with one credit. TransactionTestCase allows actual transaction boundaries, unlike regularTestCase, whose enclosing transactions can hide lock-usage mistakes.

A skipped test on SQLite doesn't verify PostgreSQL’s lock behaviour.

The run_two() helper gives the same action to two worker threads.

ThreadPoolExecutor(max_workers=2) provides the workers, and each pool.submit(worker) schedules one call. A future represents that call’s eventual result, which future.result(timeout=15) retrieves or raises an error for. Each worker clears unusable old connections before the action and closes its own connections, including when the action fails.

This lets the two operations reach the same database through separate connections.

Confirm the Unsafe Behaviour

Add this method insideConcurrencyTests, at the same indentation level as run_two():

 def test_reproduce_unsafe_spending(self):
        both_have_read = Barrier(2)
        original_get = CreditAccount.objects.get

        def read_then_wait(*args, **kwargs):
            account = original_get(*args, **kwargs)
            both_have_read.wait(timeout=5)
            return account

        with patch(
            "credits.services.CreditAccount.objects.get",
            side_effect=read_then_wait,
        ):
            self.run_two(
                lambda: reserve_generation_unsafe(self.user.pk, "A garden").pk
            )

        self.account.refresh_from_db()
        self.assertEqual(self.account.balance, 0)
        self.assertEqual(Generation.objects.count(), 2)

This test forces both unsafe operations to read before either proceeds.

original_get keeps the real lookup, and read_then_wait() calls it before waiting at Barrier(2). The barrier releases the workers only after both arrive, or raises an error if its wait times out. patch() temporarily replaces the service’s lookup with this wrapper for the duration of the with block.

The database read stays real while the test controls the pause after it.

The final assertions document the deliberately incorrect result.

The small lambda calls the unsafe function and returns the created record’s identifier for each worker. After both return, refresh_from_db() reloads the account. The assertions expect a zero balance and two generation records in this isolated test.

A pass here confirms reproduction of the bug, not correctness of the unsafe function.

Check the Protected Endpoint

Add these methods inside the same class:

def concurrent_api_requests(self):
        ready = Barrier(2)

        def send_request():
            client = APIClient()
            client.force_authenticate(self.user)
            ready.wait(timeout=5)
            return client.post(
                "/api/generate/",
                {"prompt": "A garden"},
                format="json",
            ).status_code

        return self.run_two(send_request)

    def test_last_credit_accepts_only_one_request(self):
        self.assertEqual(sorted(self.concurrent_api_requests()), [201, 409])
        self.account.refresh_from_db()
        self.assertEqual(self.account.balance, 0)
        self.assertEqual(Generation.objects.count(), 1)

    def test_two_credits_accept_both_requests(self):
        self.account.balance = 2
        self.account.save(update_fields=["balance"])

        self.assertEqual(self.concurrent_api_requests(), [201, 201])
        self.account.refresh_from_db()
        self.assertEqual(self.account.balance, 0)
        self.assertEqual(Generation.objects.count(), 2)

The request helper sends two authenticated requests through the protected view.

Each worker creates its ownAPIClient, and force_authenticate() supplies the test user without a password exchange. The barrier sits before post() so both workers reach the request start together. Each call returns its response code to run_two().

This tests the endpoint’s credit behaviour without also testing the authentication mechanism.

The two test methods cover both insufficient and sufficient shared credit.

The one-credit test sorts the codes because either worker may finish first, then expects one 201 and one 409. It also checks zero remaining credits and exactly one generation record. The two-credit test changes the starting balance and expects two successes, two records, and a zero balance.

Checking the records as well as the responses helps catch an incorrectly accepted generation.

The barrier coordinates request starts without controlling every database operation.

One request could still progress faster than the other. Moving the barrier after lock acquisition would make the first worker wait for a second worker that can't acquire its lock. The current placement avoids that artificial deadlock but doesn't prove every possible execution order.

Use this regression test alongside the controlled reproduction and documented database behaviour.

Verify the Service Encounters a Held Lock

We can also test whether the reservation function waits for a lock before it checks the balance.

The test below starts with zero credits so the balance check would immediately reject an unprotected read. The main connection acquires the account lock before it starts a worker. That worker calls the actual reservation function with a one-second lock timeout.

Add this method inside ConcurrencyTests:

    def test_reservation_waits_for_account_lock(self):
        self.account.balance = 0
        self.account.save(update_fields=["balance"])
        user_id = self.user.pk

        def attempt_reservation():
            close_old_connections()
            try:
                try:
                    with transaction.atomic():
                        with connection.cursor() as cursor:
                            cursor.execute("SET LOCAL lock_timeout = '1s'")
                        reserve_generation(user_id, "A garden")
                except OperationalError as error:
                    return error.__cause__.sqlstate
                except InsufficientCredits:
                    return "insufficient_credits"
                return "accepted"
            finally:
                connections.close_all()

        with ThreadPoolExecutor(max_workers=1) as pool:
            with transaction.atomic():
                CreditAccount.objects.select_for_update().get(pk=self.account.pk)
                result = pool.submit(attempt_reservation).result(timeout=5)
                self.assertEqual(result, "55P03")

            result = pool.submit(attempt_reservation).result(timeout=5)
            self.assertEqual(result, "insufficient_credits")

        self.account.refresh_from_db()
        self.assertEqual(self.account.balance, 0)
        self.assertEqual(Generation.objects.count(), 0)

This test controls when the competing lock exists.

The main connection keeps its transaction open while it waits for the worker’s result. Inside the worker’s transaction, SET LOCAL temporarily shortens the lock timeout. The worker should return PostgreSQL’s 55P03 error code, which means lock_not_available, after the lock wait times out.

A balance rejection at this point would show that the service didn't wait for the account lock before its check.

The second call checks the same operation after the main transaction releases its lock.

This time, the worker can acquire the account lock and read the zero balance. It should return insufficient_credits rather than a database error. The final assertions confirm no credit or generation record changed during either attempt.

Together, the two calls check contention and release without relying on two requests happening to overlap.

The zero balance is deliberate and makes the test more specific.

If we used one credit, an unprotected function might still encounter the lock when it eventually tried to update the row. With zero credits, that function would reject the request before any update and fail our expected timeout assertion. The test therefore checks the service’s lock-before-check behaviour, while the preceding endpoint tests check its spending outcomes.

This controlled lock test passed as part of the companion project’s PostgreSQL test suite.

Check Rollback After a Failure

Outside ConcurrencyTests add another class:

class CreditRollbackTests(TransactionTestCase):
    def test_failed_record_creation_restores_credit(self):
        user = get_user_model().objects.create_user(username="rollback-reader")
        account = CreditAccount.objects.create(user=user, balance=1)

        with patch(
            "credits.services.Generation.objects.create",
            side_effect=RuntimeError("Simulated record creation failure"),
        ):
            with self.assertRaises(RuntimeError):
                reserve_generation(user.pk, "A garden")

        account.refresh_from_db()
        self.assertEqual(account.balance, 1)
        self.assertEqual(Generation.objects.count(), 0)

This test deliberately raises an exception during generation-record creation.

It first creates an account with one credit. The patch makes Generation.objects.create() raise RuntimeError, and assertRaises() confirms that the error leaves the reservation function. After the transaction rolls back, the refreshed account should still have one credit and no generation record.

This checks that a failed reservation doesn't leave a deduction behind.

Run the tests with PostgreSQL still available:

python manage.py test credits -v 2

This command runs the tests in the credits app.

-v 2 asks Django to show each test and its outcome. Django creates a separate test database, so the database user needs permission to create it. The user from our local container has that permission, but an existing database setup may need configuration.

Expect five passes on the intended PostgreSQL setup. Confirm them by execution before relying on the example.

Common Mistakes and Next Steps

The example now protects the credit decision, but a few details are easy to miss when you adapt it.

Read the Account Inside the Lock

Fetching an account before the transaction and continuing to use that object can leave you with an old balance. The protected function deliberately retrieves the account through select_for_update() before making its decision.

Keep this order when you move the code into another service or endpoint. Passing in a user identifier makes the function responsible for its own fresh, locked read.

Use the Database as the Shared Point of Coordination

Disabling a submit button can reduce accidental clicks, but a second tab or another client can still send a request. A Python thread lock also coordinates only the code sharing that lock in the same process.

If you run multiple application workers, the credit decision still needs protection at the shared database. Review other balance updates, including administrative adjustments, rather than assuming this endpoint is the only writer.

Consider a Conditional Update for Simpler Counters

Row locks are one approach. For a simple deduction, Django can also express the balance condition and subtraction in one database update using an F() expression.

The condition matters: an unconditional subtraction doesn't enforce sufficient credit. If you also create a generation record, keep the deduction and record creation in one transaction.

We used an explicit lock here because it makes the read, decision, and update easy to follow. You can explore conditional updates once you understand what the operation must protect.

Separate Concurrent Requests from Retries

Our example treats two submissions as two distinct requests. If the user has two credits, both should succeed.

A retry introduces a different requirement. The app might accept a generation but lose the response before the client receives it. If the client resends the same logical request, you may want to return the original result without another charge.

That requires idempotency: a way to identify a repeated operation and avoid applying its effect again. A typical design uses a request key, a database uniqueness rule, and a stored result. A balance lock alone doesn't identify duplicate intent.

Plan for Provider Failures

Once the reservation commits, a later provider failure doesn't automatically restore the credit. You need a policy for whether to retry the generation, refund it, or leave it pending for recovery.

A real implementation also needs to recover if the application stops after it reserves the credit but before it starts the job. The reserved record gives you something to track, but this tutorial doesn't implement a durable job queue or recovery worker.

Keep those concerns visible when you extend the example. Preventing concurrent overspending is one part of a complete credit system.

Summary and Next Steps

At the start of this guide, two requests could each pass the balance check and spend the same credit. The balance ended at zero, which made the failure easy to overlook.

We reproduced the sequence, then protected the decision with a transaction and a row lock. We also checked the generation count, tested the case where both requests had enough credit, and added a rollback test for record creation failure.

When you review a similar feature in your own application:

1. State the rule the data must satisfy, such as one credit per accepted generation.

2. Identify where separate requests can read and change the same value.

3. Protect the decision and its related database changes.

4. Test overlapping operations and failures on the database you actually use.

The same reasoning applies to the last item in an online store or any shared allowance. A successful check is only useful if the application can safely act on it.

References

For a deeper look at retries, see Making retries safe with idempotent APIs.

In this article, we’ll walk step by step through how performance issues arise in Django REST APIs, how to see them clearly using profiling tools, and how to fix them using query optimization, caching, pagination, and basic scaling strategies.

This article will be most useful for developers who already understand Django, the Django REST Framework, and REST concepts, but are new to performance optimization.

What we’ll cover:

• Why Django REST APIs Become Slow

• Profiling: Finding the Real Bottlenecks

• Logging SQL Queries

• Summary and Next Steps

Why Django REST APIs Become Slow

Before optimizing anything, it’s important to understand why APIs become slow in the first place.

Most performance issues in Django REST APIs come from three main sources:

1. Too many database queries

2. Doing expensive work repeatedly

3. Returning more data than necessary

Django is fast by default, but it does exactly what you ask it to do. If your API endpoint triggers 300 database queries, Django will happily run all 300.

Now let’s look at some common causes of performance issues in Django REST APIs.

1. N+1 Query Problems in Serializers

This happens when you loop over objects and access related fields, causing a separate query for each object.

# models.py
class Author(models.Model):
    name = models.CharField(max_length=100)

class Post(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.CASCADE)

# views.py (naive approach)
posts = Post.objects.all()
for post in posts:
    # This triggers a query per post to fetch the author
    print(post.author.name)

If you have 100 posts, this runs 101 queries: 1 for posts and 100 for authors. Django lazily loads related objects by default, so without intervention, your API performs repetitive database work that slows response times.

2. Fetching Related Objects Inefficiently

# Naive queryset fetching all related objects separately
posts = Post.objects.all()
authors = [post.author for post in posts]  # triggers extra queries per post

Each access to post.author triggers a new query. Even though you already fetched all posts, Django lazily loads related objects by default. This creates many extra queries, slowing down your API.

3. Serializing Large Datasets Without Pagination

Returning large query sets all at once can slow down your API and increase memory usage.

# views.py
from rest_framework.response import Response
from rest_framework.decorators import api_view
from .models import Post
from .serializers import PostSerializer

@api_view(['GET'])
def all_posts(request):
    posts = Post.objects.all()  # retrieves all posts at once
    serializer = PostSerializer(posts, many=True)
    return Response(serializer.data)

If your database has thousands of posts, this endpoint fetches everything in memory, serializes it, and sends it over the network. It’s slow and can crash under load. Later, we’ll learn to paginate results efficiently.

4. Recomputing Expensive Work Repeatedly

Some endpoints calculate the same values on every request instead of caching or precomputing.

def expensive_view(request):
    # Simulate expensive computation
    result = sum([i**2 for i in range(1000000)])
    return JsonResponse({"result": result})

Even if the data doesn’t change often, this computation happens on every request, consuming CPU time unnecessarily.

Performance optimization is about reducing unnecessary work.

At this point, it might be tempting to jump straight into fixes like caching responses or optimizing database queries. But doing that without evidence often leads to wasted effort or even new problems.

Before changing anything, you need to understand where your API is actually spending time. Is it the database? Is it serialization? Is it Python code running repeatedly on every request? This is where profiling becomes essential.

Profiling: Finding the Real Bottlenecks

Optimizing without profiling is guessing. Profiling helps you answer one question:

Where is my API actually spending time?

In practice, profiling means observing an API while it runs and collecting data about what it’s doing. This includes how many database queries are executed, how long those queries take, and how much time is spent in Python code, such as serializers or business logic.

By profiling first, you avoid making assumptions and can focus on fixing the parts of your API that are truly slowing things down.

Measuring Query Count in a View

During development, Django keeps track of all executed queries. You can inspect them directly:

from django.db import connection
from rest_framework.decorators import api_view
from rest_framework.response import Response
from .models import Post
from .serializers import PostSerializer

@api_view(["GET"])
def post_list(request):
    posts = Post.objects.all()
    serializer = PostSerializer(posts, many=True)

    response = Response(serializer.data)

    print(f"Total queries executed: {len(connection.queries)}")

    return response

If this prints 101 queries for 100 posts, you likely have an N+1 problem. This simple check confirms whether the database layer is the bottleneck.

One of the easiest ways to profile Django applications during development is by using tools that expose this information directly while requests are being processed.

Using the Django Debug Toolbar

The Django Debug Toolbar is one of the simplest ways to understand performance during development. It acts as a lightweight profiling tool that shows what happens behind the scenes when a request is handled.

It shows you:

• How many SQL queries were executed

• How long each query took

• whether queries are duplicated

• Which parts of the request lifecycle are slow

How to Install and Enable the Django Debug Toolbar

First, install it:

pip install django-debug-toolbar

In settings.py:

INSTALLED_APPS = [
    ...
    "debug_toolbar",
]

MIDDLEWARE = [
    ...
    "debug_toolbar.middleware.DebugToolbarMiddleware",
]

INTERNAL_IPS = [
    "127.0.0.1",
]

In urls.py:

import debug_toolbar
from django.urls import path, include

urlpatterns = [
    ...
    path("__debug__/", include(debug_toolbar.urls)),
]

When you load an endpoint in the browser during development, the toolbar displays total SQL queries, execution time, and duplicate queries. This makes inefficiencies immediately visible.

When you load an API endpoint and see 150 SQL queries for a single request, that’s a strong signal that something is wrong, often an N+1 query problem or inefficient serializer behavior.

Logging SQL Queries

Django allows you to log all executed SQL queries. This is especially useful when debugging API views.

Seeing the raw SQL makes inefficiencies obvious, such as repeated SELECT statements for the same table.

How to Enable SQL Query Logging

You can configure Django to log all SQL queries in settings.py:

LOGGING = {
    "version": 1,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
        },
    },
    "loggers": {
        "django.db.backends": {
            "handlers": ["console"],
            "level": "DEBUG",
        },
    },
}

With this configuration, every SQL query will be printed to the console when your API runs. Repeated SELECT statements or unexpected queries become obvious.

Profiling API Response Time

Database queries are only one part of API performance. Beyond queries, it’s also important to measure the total response time of an endpoint.

Profiling response time helps you understand whether delays are caused by database access or by other parts of the request lifecycle. For example, if an endpoint takes 1.2 seconds to respond but only 50 milliseconds are spent on database queries, the bottleneck is likely in serialization, business logic, or repeated computations in Python.

By comparing query time and total response time, profiling helps you identify what to fix first instead of optimizing the wrong layer of the system.

How to Measure Total Response Time

import time
from rest_framework.decorators import api_view
from rest_framework.response import Response

@api_view(["GET"])
def example_view(request):
    start_time = time.time()

    # Simulate work
    data = {"message": "Hello world"}

    response = Response(data)

    end_time = time.time()
    print(f"Response time: {end_time - start_time:.4f} seconds")

    return response

If database queries are fast but the total response time is high, the bottleneck may be serialization or expensive Python logic.

Once you’ve identified that database access is a significant contributor to slow response times, the next step is to look more closely at how Django retrieves related data.

SQL Query Optimization in Django REST APIs

One of the most common reasons Django REST APIs become slow is inefficient access to related objects. This often manifests as the N+1 query problem, where fetching related objects triggers a separate database query for each item. Identifying and fixing this problem can significantly reduce the number of queries and improve API performance.

Understanding the N+1 Query Problem

Consider a simple example:

• You fetch a list of posts

• Each post has an author

• For every post, Django fetches the author separately

If you have 100 posts, this results in 101 queries: 1 for the posts and 100 for the authors. This happens because Django lazily loads related objects by default. Without intervention, your API performs repetitive database work that slows down response times.

Solving the Problem with select_related and prefetch_related

Django provides built-in tools to control how related objects are loaded efficiently: select_related and prefetch_related.

1. Using select_related

select_related is designed for foreign key and one-to-one relationships. It performs an SQL join and retrieves related objects in a single query.

Use it when:

• You know you will access related objects

• The relationship is one-to-one or many-to-one

posts = Post.objects.select_related("author")

for post in posts:
    print(post.author.name)  # No additional queries

This performs a SQL JOIN and retrieves posts and authors in a single query, eliminating the N+1 problem.

It reduces multiple queries into just one, avoiding repeated database hits.

2. Using prefetch_related

prefetch_related is used for many-to-many and reverse foreign key relationships. It performs separate queries for each related table but combines the results in Python.

Use it when:

• A SQL join would produce too much duplicated data

• You are dealing with collections of related objects

Example: How to Optimize a Many-to-Many Relationship

Consider a blog application where posts can have multiple tags:

# models.py
class Tag(models.Model):
    name = models.CharField(max_length=50)

class Post(models.Model):
    title = models.CharField(max_length=200)
    tags = models.ManyToManyField(Tag)

Now imagine fetching posts and accessing their tags:

posts = Post.objects.all()

for post in posts:
    print(post.tags.all())  # Triggers additional queries

If you have 100 posts, Django may execute:

• 1 query to fetch posts

• 1 query per post to fetch related tags

This results in many unnecessary database hits.

You can optimize this using prefetch_related:

posts = Post.objects.prefetch_related("tags")

for post in posts:
    print(post.tags.all())  # Uses prefetched data

With this approach, Django performs one query for posts and one query for all related tags. It then matches them in Python, eliminating repeated database queries.

Together, these tools allow you to optimize your queries and eliminate the N+1 problem efficiently.

Common Beginner Mistakes

Even after applying these optimizations, it’s easy to make mistakes. Watch out for:

• Forgetting that serializers can trigger additional queries

• Using select_related on many-to-many relationships

• Assuming Django automatically optimizes queries

• Not checking the query count after adding serializers

Paying attention to these pitfalls ensures your API remains fast and scalable.

Caching in Django REST APIs

Even after optimizing database queries, API performance can still suffer if the same computations or database lookups are performed repeatedly. This is where caching comes in. Caching is a technique for storing the results of expensive operations so they can be retrieved more quickly the next time they are needed.

At its core, caching exists because computers have multiple layers of memory with different speeds:

• CPU registers (fastest)

• L1, L2, L3 caches

• Main memory (RAM)

• SSD storage

• HDD storage (slowest)

Each layer trades speed for size: the closer the data is to the CPU, the faster it can be accessed. Software systems use the same principle; by storing frequently accessed data in a “closer” or faster location, applications can respond more quickly.

Cache Eviction

Caches are limited in size, so when a cache is full, some data must be removed to make room for new data. This process is called cache eviction.

Common eviction strategies include:

• Least Recently Used (LRU): removes the data that hasn’t been accessed for the longest time

• Random Replacement: removes a random item from the cache

The goal is to keep the data that is most likely to be requested again while freeing space for new data. Understanding this helps developers use caching effectively.

Caching in Application Architectures

Caching exists at several levels in modern software systems:

• Client-side caching: Web browsers cache HTTP responses to reduce the need for repeated network requests. This is controlled with HTTP headers like Cache-Control.

• CDN caching: Content Delivery Networks store static assets closer to users, reducing latency and server load.

• Backend caching: Backend services cache results from database queries, computed values, or API responses. This is where Django caching is most commonly applied.

By applying caching strategically at the backend, APIs can serve data faster while reducing computation and database load.

Caching in Django

Django provides a flexible caching framework that supports multiple backends, including in-memory, file-based, database-backed, and third-party stores like Redis. The main types of caching in Django are:

1. Per-view caching: caches the entire output of a view. Ideal for endpoints where responses rarely change.

    from django.views.decorators.cache import cache_page
   
    @cache_page(60 * 15)  # cache for 15 minutes
    def my_view(request):
   

   2. Template fragment caching: caches specific parts of a template to avoid repeated rendering.

   3. Low-level caching: gives full control over what is cached and for how long, making it ideal for API responses.

By combining these approaches, you can reduce repeated work in your API, lower database load, and speed up response times.

When to Use Redis

While Django’s built-in caching backends are sufficient for many projects, high-traffic APIs often require a shared, in-memory cache. This is where Redis excels. Redis is designed for fast access, low latency, and can handle frequent reads across multiple servers.

You should consider using Redis when:

• Data is read frequently but changes infrequently

• Low latency is important for API responses

• You need cache expiration and eviction policies

• You want a shared cache across multiple servers or services

Redis is particularly effective for API endpoints that serve the same data to many users, such as frequently accessed lists or computed results.

Common Beginner Mistakes

Caching is powerful, but it’s easy to misuse. Some common pitfalls include:

• Caching everything blindly: not all data benefits from caching

• Forgetting cache invalidation: stale data can lead to incorrect responses

• Using cache where query optimization would suffice: sometimes optimizing database queries is a better solution than caching.

Remember: caching should complement good database design, not replace it.

Pagination and Limiting Expensive Datasets

Even with caching, returning large datasets in a single request can slow down your API and increase memory usage. Pagination is a simple and effective way to limit the amount of data returned at once.

Pagination helps by reducing:

• Database load

• Memory usage

• Serialization time

• Network transfer size

Django REST Framework provides built-in pagination classes that make it easy to paginate endpoints. As a rule of thumb, always paginate list endpoints unless there is a strong reason not to.

Load Testing and Measuring Improvement

Optimizations are only meaningful if you can measure their impact. Load testing simulates multiple users accessing your API simultaneously, helping you answer key questions:

• How many requests per second can my API handle?

• Where does the API start to break under load?

• Did caching, query optimization, and pagination actually improve performance?

By running load tests before and after optimization, you can validate that your changes have the desired effect and avoid optimizing the wrong parts of your system.

Summary and Next Steps

Optimizing Django REST APIs isn’t about chasing every tiny micro-optimization. It’s about reducing unnecessary work and focusing on the parts of your API that actually slow down performance.

Key Takeaways

• Profile before optimizing: Identify the real bottlenecks before making changes.

• Reduce database queries: Use techniques like select_related, prefetch_related, and avoid N+1 queries.

• Cache frequently accessed data: Use Django caching and Redis to reduce repeated computations.

• Paginate large datasets: Limit memory usage and network load by returning data in chunks.

• Measure performance changes: Always verify that your optimizations have a real impact.

Next Steps for Your APIs

1. Add profiling to your existing APIs to understand where time is spent.

2. Identify one slow endpoint and focus on optimizing it first.

3. Optimize database queries using Django ORM best practices.

4. Introduce caching carefully; avoid caching everything blindly.

5. Measure the results with load testing and performance metrics.

Remember: Performance optimization is not a one-time task. It’s a habit built by continuously observing how your system works, testing improvements, and applying changes where they make the most impact.

Read More

1. DRF Performance

2. Django ORM Optimization

3. Understanding N+1 queries

So, how does one actually think like a backend developer? Before answering that, let’s start with the basics: what exactly is backend development?

Table of Contents

• What is Backend Development?

• Why Django REST Framework?

  • Flask

  • FastAPI

  • Django REST Framework

• How to Think Like a Backend Developer

  • 1. Think in Systems, Not Lines of Code

  • 2. Separate Concerns — Keep Things Organized

  • 3. Anticipate Problems Before They Happen

  • 4. Make Your Code Predictable and Readable

  • 5. Think in the Request → Logic → Response Cycle

  • 6. Practice Thinking Like a Backend Developer

• How to Install the Django REST Framework

  • Step 1: Install Python

  • Step 2: Create a Project Folder

  • Step 3: Create a Virtual Environment

  • Step 4: Install Django

  • Step 5: Create a Django Project

  • Step 6: Install Django REST Framework

  • Step 7: Add DRF to Installed Apps

  • Step 8: Run Initial Migrations

  • Step 9: Start the Server

  • Step 10: Verify DRF Installation

• The Backend Developer’s Mindset

• Common Mistakes Beginners Make

• Further Reading

• Conclusion

What is Backend Development?

Backend development is the foundation of most web and mobile applications. It focuses on everything that happens behind the scenes, from processing logic and handling data to connecting with databases and APIs.

While it’s true that backend developers build APIs that communicate with the frontend, the job goes far beyond that. The backend is where data is validated, protected, stored, and retrieved.

In short: backend development is about building systems that ensure data integrity, performance, and scalability.

Backend developers are the ones responsible for designing and maintaining those systems. They ensure that every user request is processed efficiently and securely.

Now, how does the Django REST Framework (DRF) fit into all this?

Why Django REST Framework?

A beginner-friendly tutorial must use a tool that:

• Teaches good structure

• Encourages best practices

• Hides unnecessary complexity

• Helps you learn backend fundamentals correctly

That’s why this guide uses the Django REST Framework (DRF). Here’s how it compares to other popular Python frameworks.

Flask

Flask is a lightweight and flexible microframework. It is great for small projects, but:

• You have to set up everything manually (routing, JSON handling, database handling).

• You need extra libraries for authentication, validation, or serialization.

• Beginners often create unstructured projects because Flask doesn’t enforce architecture.

Flask teaches freedom, not structure.

FastAPI

FastAPI is modern, fast, and async-first. However:

• It assumes you already understand APIs.

• It requires understanding Python type hints deeply.

• The ecosystem is still growing.

• Beginners may not understand its underlying concepts (dependency injection, async IO).

FastAPI teaches speed, not fundamentals.

Django REST Framework

DRF is ideal for beginners because:

• It sits on top of Django, a very stable full-stack framework.

• It encourages good architecture from day one.

• It handles serialization, authentication, routing, validation, and permissions for you.

• It gives you structure instead of chaos.

Bottom line: DRF can help you learn how backend systems work from scratch.

How to Think Like a Backend Developer

Thinking like a backend developer is not about memorizing code. It’s about learning to see the bigger picture, how data moves, how logic flows, and how to build systems that work reliably and can grow.

Backend thinking can be summarized into six main principles:

1. Think in Systems, Not Lines of Code

Many beginners focus on writing code that works for one feature. A backend developer thinks about the entire system.

Analogy: Imagine a factory. Each machine (function or endpoint) does one task, but the factory only works efficiently if every machine is arranged correctly and communicates properly.

Example: When a user submits a form to create a task:

• The request reaches the server.

• The backend validates the data.

• The backend stores it in the database.

• The backend sends a response to the user.

A backend developer doesn’t just write a function to save data. They ask:

• Where should this logic live — view, serializer, or service layer?

• How will the data be validated and cleaned?

• How will the system scale if thousands of users submit tasks at the same time?

Seeing the system first makes code predictable, maintainable, and scalable.

2. Separate Concerns — Keep Things Organized

Backend thinking is about structure. Every piece of code should have a clear responsibility:

• Models: Store and define your data

• Serializers: Convert data to a format the client understands (like JSON)

• Views: Apply the business logic and respond to requests

Why this matters: Without separation, code becomes messy and hard to debug. You might find yourself mixing database queries with validation or formatting, which leads to errors later.

Simple analogy: Think of a restaurant.

• The chef prepares the food (model/data).

• The waiter delivers the food to customers in a presentable way (serializer).

• The manager decides who gets what and handles special requests (view/logic).

Each role is separate but connected. This is exactly how backend developers structure code.

3. Anticipate Problems Before They Happen

Backend developers don’t just code for today. They think ahead:

• What if the user sends invalid data?

• What if two users try to edit the same record at the same time?

• How will the system handle millions of requests in the future?

Example: If a user tries to create a task without a title, a beginner might just let it crash. A backend developer writes validation rules to catch this and return a clear error message.

Rule of thumb: Always ask, “What could go wrong here?” and design your code to handle it gracefully.

4. Make Your Code Predictable and Readable

Backend development is about writing code for humans, not just computers.

• Use clear variable names (task_title instead of x).

• Keep functions short and focused.

• Document your code.

This way, anyone can pick up your code and understand it, including your future self.

Tip: A backend system that is easy to read and predict is easier to debug, extend, and scale.

5. Think in the Request → Logic → Response Cycle

Every backend action fits into this pattern:

• Request: The client sends data.

• Logic: The server validates, processes, and decides what to do.

• Response: The server sends data back in a structured way.

Example: User creates a task:

• Request: { "title": "Learn DRF" }

• Logic: Check title is not empty → save to database → mark completed as False

• Response: { "id": 1, "title": "Learn DRF", "completed": false }

Thinking in this cycle makes debugging and designing systems intuitive.

6. Practice Thinking Like a Backend Developer

• Ask questions before coding: “Where should this logic live? How will this affect other parts of the system?”

• Break down problems into steps: Don’t just code the solution; code the process.

• Visualize data flow: Draw diagrams if necessary, from user request to database and back.

• Learn by doing: Build small projects and reflect on each component’s role.

Check out Andy Harris’s video on how to think like a programmer.

Now that you understand how backend developers think, let’s walk through setting up a real backend environment using Django REST Framework.

How to Install the Django REST Framework

Here’s how to get the Django REST framework running on your machine from scratch.

Step 1: Install Python

Make sure you have Python 3.8+ installed. You can check if Python is installed with this command:

python --version

If it’s not installed, download it from the official Python documentation.

Step 2: Create a Project Folder

Choose a location on your computer and create a folder for your project:

mkdir my_drf_project
cd my_drf_project

This keeps all your files organized in one place.

Step 3: Create a Virtual Environment

A virtual environment keeps your project dependencies separate from other projects.

Create a virtual environment:

python -m venv venv

Next, activate it. For Windows (PowerShell):

.\venv\Scripts\Activate.ps1

For Mac/Linux:

source venv/bin/activate

You’ll know it’s active when your terminal prompt starts with (venv).

Step 4: Install Django

Now install Django inside the virtual environment:

pip install django

Check that Django is installed:

python -m django --version

Step 5: Create a Django Project

Create a new Django project:

django-admin startproject core .

The . at the end means “create the project here.” Run the server to make sure it works:

python manage.py runserver

Visit http://127.0.0.1:8000/ in your browser. You should see the Django welcome page.

Step 6: Install Django REST Framework

Install DRF using pip:

pip install djangorestframework

Step 7: Add DRF to Installed Apps

Open core/settings.py and find the INSTALLED_APPS list. Add:

'rest_framework',

It should look like this:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
]

Step 8: Run Initial Migrations

Set up your database:

python manage.py migrate

Create a superuser for accessing the admin panel:

python manage.py createsuperuser

Follow the prompts for username, email, and password.

Step 9: Start the Server

Run your development server again:

python manage.py runserver

Visit:

• http://127.0.0.1:8000/ → Django welcome page

• http://127.0.0.1:8000/admin/ → Admin panel (login with superuser)

You now have Django + DRF installed and ready for API development.

Step 10: Verify DRF Installation

The easiest way to confirm that Django REST Framework is installed correctly is to build a very small test API. Each part of the setup helps you verify that DRF is working end-to-end.

Create a new app:

python manage.py startapp api

This creates an api folder where you’ll place your test model, serializer, and view. Adding it to INSTALLED_APPS tells Django to recognize the new app.

Add it to INSTALLED_APPS:

'api',

Create a simple models.py in the api app:

from django.db import models

class Task(models.Model):
    title = models.CharField(max_length=200)
    completed = models.BooleanField(default=False)

This model represents a basic task with a title and a completion status. Creating even a simple model lets you test whether DRF can serialize and expose database objects as API responses.

Run migrations:

python manage.py makemigrations
python manage.py migrate

These commands generate and apply database tables for the Task model. Without migrations, DRF won’t have anything to fetch and serialize.

Create a serializer (api/serializers.py):

from rest_framework import serializers
from .models import Task

class TaskSerializer(serializers.ModelSerializer):
    class Meta:
        model = Task
        fields = '__all__'

A serializer converts your Task model into JSON so it can be returned as an API response. This step confirms that DRF’s serializer tools are working.

Create a view (api/views.py):

from rest_framework import viewsets
from .models import Task
from .serializers import TaskSerializer

class TaskViewSet(viewsets.ModelViewSet):
    queryset = Task.objects.all()
    serializer_class = TaskSerializer

ModelViewSet automatically creates the CRUD API endpoints for your model. If this loads correctly, it means DRF’s generic views and viewsets are functioning.

Wire it to URLs (core/urls.py):

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from api.views import TaskViewSet

router = DefaultRouter()
router.register('tasks', TaskViewSet)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include(router.urls)),
]

The router generates routes /api/tasks/ for you. If routing works, DRF is properly integrated into your Django project.

Test the API by visiting:

http://127.0.0.1:8000/api/tasks/

If everything is set up correctly, you’ll see Django REST Framework’s browsable API. This confirms that DRF is installed, your project recognizes it, and it can serialize and return data successfully.

The Backend Developer’s Mindset

When writing backend code, your goal isn’t just to make something work; it’s to make it predictable, scalable, and maintainable.

Professional backend developers focus on:

• Predictability over cleverness — Code should be clear to others.

• Separation of concerns — Keep logic, data, and presentation layers distinct.

• Validation — Never trust user input; always validate.

• Consistency — Stick to naming conventions and reusable patterns.

This mindset is what separates backend coders from backend engineers.

Common Mistakes Beginners Make

• Writing too much logic in views: Keep views light. Move business logic into services or serializers.

• Ignoring validation: Always define validation rules in your serializers.

• Not planning for scalability: Even small projects grow. Build like you expect more users.

Further Reading

Django official documentation

How to Build a REST API in Django

What is Serialization?

REST API Best Practices – REST Endpoint Design Examples

Conclusion

Thinking like a backend developer isn’t about memorizing syntax; it’s about understanding how systems behave.

When you start reasoning through requests, logic, and responses, you begin to see the bigger picture, and that’s when you stop writing code and start building systems.

With Django REST Framework, that process becomes easier, cleaner, and more intuitive.

As you continue learning, build small APIs and gradually add features. The more you understand how data flows through a system, the more naturally backend thinking will come.