Structuring a Django REST Framework API Project: How Do I Go About It?

This is my first technical blog post. More will follow on Django, architecture, and things I learned the hard way. Discussion is very welcome.

---

A few weeks ago, a senior Django developer (more experienced than me 😅) joined a project I had been building solo. After reviewing the codebase, he sent me this message (translated and paraphrased from French):

"There are quite a few things that are not well finished. Some deficiencies. But there are also some very beautiful things that allowed me to move fast."

That last sentence is why I told myself: why not start writing, both to preserve what worked and to connect with others? So here I am. 👋

Properly structuring a project, especially a large one, is crucial. It's about making decisions early that let you, and others, navigate confidently, add features safely, and hand the project off without needing to be called back every five minutes.

Let's get into it. 🚀

---

The Problem With Django's Default Layout

When you run django-admin startproject backend, you get this:

backend/
├── backend/
│   ├── settings.py
│   ├── urls.py
│   ├── wsgi.py
│   └── asgi.py
├── manage.py

Then you add your first app:

python manage.py startapp myapp

And suddenly:

backend/
├── myapp/
│   ├── models.py
│   ├── views.py
│   ├── admin.py
│   └── tests.py
├── backend/
│   └── settings.py

This works perfectly. For a tutorial. 😬

In a real production context, models.py quickly hits 1,000+ lines. views.py becomes a novel. settings.py mixes database config, email config, AWS config, etc.

The structure that scales is not the one you start with. It's the one you design from day one.

Let's fix that.

---

1. The Top-Level Split: apps/ and backend/

The first and most impactful decision: separate your Django apps from your project configuration.

my-project/
├── backend/           ← Django project config (settings, urls, celery…)
├── apps/              ← All your Django apps live here
├── docs/              ← Documentation
├── scripts/           ← Utility scripts
├── tests/             ← Test suite
├── manage.py
└── requirements.txt

Any developer opening this repo for the first time immediately understands the map:

• backend/ → framework config, don't touch without a reason
• apps/ → this is where the features and business logics are implemented

Simple. Obvious. Zero ambiguity. That's the goal.

---

2. The backend/ Folder: Config That Breathes

Still with me? Good. 👌

The most common mistake inside backend/ is keeping a single monolithic settings.py. JWT, email, AWS, rate limiting: all in one file becomes a wall with no structure.

Split settings by domain:

backend/
├── settings/
│   ├── __init__.py      ← Loads sub-modules
│   ├── base.py          ← Core Django config (installed apps, middleware, DB…)
│   ├── smtp.py          ← Email config only
│   └── configs/
│       └── storages.py  ← S3/media storage config
├── urls.py              ← Root URL dispatcher
├── celery.py            ← Celery app init (if using async tasks)
├── asgi.py
└── wsgi.py

# backend/settings/smtp.py: email concerns only
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = os.environ.get("EMAIL_HOST")
EMAIL_PORT = int(os.environ.get("EMAIL_PORT", 587))
EMAIL_USE_TLS = True

# backend/settings/configs/storages.py: storage concerns only
DEFAULT_FILE_STORAGE = "storages.backends.s3boto3.S3Boto3Storage"
AWS_STORAGE_BUCKET_NAME = os.environ.get("AWS_BUCKET_NAME")

When a DevOps engineer needs to update email config, they go directly to smtp.py. They don't have to read 400 lines of unrelated settings. This is respect for the next developer's time. 🙏

---

3. The apps/ Folder: One Domain, One App

Every feature domain gets its own Django app. No monolithic core/ app that holds everything.

apps/
├── authentication/    ← Registration, login, JWT…
├── transactions/      ← Transactions, refunds…
├── users/             ← User model, profiles…
├── notifications/     ← Email, SMS, Push, WhatsApp…
├── marketing/         ← Referrals, contact messages…
├── settings/          ← System and per-user settings
└── utils/             ← Shared code (base model, enums, errors, middleware)

Each app is a bounded context: it owns its models, its views, its serializers, its business logic. If tomorrow you extract notifications/ into a separate microservice, the limits are already drawn.

The rule I apply: if you can describe it in one domain noun, it's an app. Authentication, Transactions, Notifications. Not Stuff, not Core, not Api.

---

4. Inside an App: Every File Has a Job

Still following? 👀 This is where most Django projects diverge from best practices.

The generated models.py / views.py monolith pattern doesn't scale. Here's what a well-structured app looks like instead:

apps/transactions/
├── models/
│   ├── __init__.py          ← Star-imports all model files
│   ├── transactions.py
│   ├── refunds.py
│   └── …
├── serializers/
│   ├── transactions.py
│   ├── refunds.py
│   └── …
├── views/
│   ├── transactions.py
│   ├── refunds.py
│   └── …
├── services/
│   ├── transaction_processor.py
│   └── refund_service.py
├── admin/
│   ├── __init__.py
│   └── transactions.py
├── router.py
├── urls.py
├── tasks.py     ← Celery tasks (can be split too)
├── apps.py
└── tests.py

Split models into sub-files

The models/__init__.py re-exports everything via star imports:

# apps/transactions/models/__init__.py
from apps.transactions.models.transactions import *
from apps.transactions.models.refunds import *

From Django's perspective, nothing changes: apps.transactions.Transaction still works. From a developer's perspective, everything changes:

• Each model file stays focused and readable (< 300 lines)
• Git merge conflicts are rare and simple to resolve when they happen
• Searching "transactions" in your file list returns models, services, serializers, all at once

The services/ layer

Views should not contain business logic. This isn't a rule I invented. It's a principle that saves you every time you need to reuse logic in a task, a management command, or a test.

# ❌ Business logic in the view — classic antipattern
class TransactionViewSet(ModelViewSet):
    def create(self, request):
        dest_user = User.objects.get(...)
        if not dest_user.is_active:
            raise ValidationError("User not available")
        # ...50 more lines of business logic...

# ✅ The view delegates to a service
class TransactionViewSet(ModelViewSet):
    def create(self, request):
        serializer = CreateTransactionSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        transaction = TransactionProcessor.create_transaction(
            user=request.user,
            **serializer.validated_data
        )
        return Response(TransactionSerializer(transaction).data)

TransactionProcessor.create_transaction() can now be called from a view, a task, a test, or a management command, without changing a single line. 💪

---

5. The Base Model: Your Foundation for Every Table

Every model in this project inherits from one class. Just one.

# apps/utils/models/base_model.py
from uuid import uuid4
from django.db import models
from django_softdelete.models import SoftDeleteModel

class AbstractCommonBaseModel(SoftDeleteModel):
    uuid = models.UUIDField(primary_key=True, default=uuid4, editable=False)
    active = models.BooleanField(default=True)
    timestamp = models.DateTimeField(auto_now_add=True)
    updated = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True

Every model then uses it:

from apps.utils.models.base_model import AbstractCommonBaseModel

class Transaction(AbstractCommonBaseModel):
    # uuid, active, timestamp, updated → already there for free
    status = models.CharField(...)
    amount = models.DecimalField(...)

Pure DRY. You get for free, on every table:

Field	Benefit
uuid (PK)	No sequential IDs leaking record counts; safe in URLs
active	Logical on/off switch
timestamp	Creation date, always available
updated	Last modification date, always available
Soft delete	.delete() marks the row deleted, doesn't destroy it

Soft delete, specifically, has become a habit over the years. You never permanently remove a sensitive record. Even if a user "deletes" something from their view, the row stays for audits, disputes, and reconciliation. 🔍

Defining this in the base model means you can never forget it. The pattern is enforced at the class hierarchy level.

---

6. The utils/ App: Your Project's Internal Library

Every project accumulates shared code. The question is whether it lives scattered everywhere or in one dedicated place.

apps/utils/
├── models/
│   └── base_model.py           ← AbstractCommonBaseModel
├── xlib/                       ← "extended library" (your project's vocabulary)
│   ├── enums/
│   │   ├── base.py             ← BaseEnum
│   │   ├── errors.py           ← All error codes
│   │   ├── transactions.py     ← TransactionStatusEnum, etc.
│   │   └── users.py            ← UserStatusEnum, etc.
│   ├── error_util.py           ← Centralized error resolution
│   ├── exceptions.py           ← Custom domain exceptions
│   └── validators.py           ← Custom validators
├── middleware/
│   └── …
├── commons/
│   └── mixins.py               ← Reusable ViewSet mixins
└── views/
    └── errors.py               ← Public error map endpoint

One pattern worth highlighting: the Enum system. Instead of scattering verbose choice tuples across model files:

# ❌ The old way, repeated everywhere
status = models.CharField(choices=[('PENDING', 'Pending'), ('FAILED', 'Failed'), ...])

# ✅ One enum, reused everywhere
from apps.utils.xlib.enums import TransactionStatusEnum

status = models.CharField(
    choices=TransactionStatusEnum.items(),
    default=TransactionStatusEnum.PENDING.value,
)

One source of truth. No copy-paste drift. 🎯

---

7. URL Routing: Three Layers, Clear Contracts

Every app follows the same three-layer URL pattern. No exceptions.

Layer 1 (router.py): Register ViewSets

# apps/transactions/router.py
from rest_framework.routers import DefaultRouter
from apps.transactions.views import TransactionViewSet, RefundViewSet

router = DefaultRouter()
router.register(r'refunds', RefundViewSet, basename='refunds')
router.register(r'', TransactionViewSet, basename='transactions')

urls_patterns = router.urls

Layer 2 (urls.py): App URL contract (router URLs + any manual path() entries)

# apps/transactions/urls.py
from apps.transactions.router import urls_patterns

urlpatterns = urls_patterns

Layer 3 (backend/urls.py): Root dispatcher, versioned

urlpatterns = [
    path("v1/auth/",          include("apps.authentication.urls")),
    path("v1/transactions/",  include("apps.transactions.urls")),
    path("v1/users/",         include("apps.users.urls")),
    # …
]

A new developer looking for "where does the transaction list endpoint come from" follows this path in under 60 seconds. No magic. No hunting. 🗺️

When you need /v2/, you add a second block without touching the first.

---

Bonus: scripts/ and docs/

Small things that signal a professional codebase:

scripts/
├── rmpycaches.py        ← Clear all __pycache__ folders
└── rmmigrationfiles.py  ← Remove migration files (for dev resets)

docs/
├── modelings/           ← (For example ) Use cases, class diagrams, sequence diagrams

---

The Real Impact

We're almost done, and this last part is the reason any of this matters. 🏁

The senior developer who reviewed my codebase moved fast. He could navigate without asking me where things were. That's the metric that matters: not "is the code clever" but "can the next person read it?"

During development:

• You never wonder "where should I put this?". The structure answers.
• Features are isolated: adding marketing/ doesn't touch transactions/
• The base model prevents forgotten patterns (timestamps, soft delete)

During code review:

• PRs stay small because changes live in one app's files
• Reviewers know exactly where to look

During onboarding:

• A new developer maps the codebase in 20 minutes by reading folder names
• backend/urls.py is the full table of contents for the API

During incidents:

• Bug in transaction creation? Check services/transaction_processor.py, not a 1,000-line views.py

During refactoring:

• Extracting notifications/ into a microservice means moving one folder, not grepping scattered code

---

Takeaway Checklist

For your next Django project, or to refactor your current one:

• [ ] Name your config folder backend/ (or config/), not after your project
• [ ] Put all apps under apps/
• [ ] Split settings.py by domain: smtp.py, storages.py, etc.
• [ ] Create AbstractCommonBaseModel with UUID PK, timestamps, and soft delete
• [ ] Split models.py into models/<domain>.py files, re-exported via __init__.py
• [ ] Add a services/ layer: views call services, not raw ORM
• [ ] Create apps/utils/ as your project's internal library
• [ ] Use enums for model choices (one source of truth)
• [ ] Follow the three-layer URL pattern: router.py → urls.py → backend/urls.py
• [ ] Add a scripts/ folder for repetitive dev commands
• [ ] Write at least a minimal docs/. Your future self will thank you.

---

What's Next

Next post: Standardized error handling in Django REST Framework, with i18n support and a React integration example.

Every API returns errors. The question is whether they're consistent, translatable, and useful to the frontend consuming them. I'll show you the ErrorEnum + ERROR_MAP pattern, how drf-standardized-errors shapes every response, and how to wire it up so a React app displays the right message in the right language, without any if/else chains.

---

If you spotted something I got wrong, or if you do it differently and it works better, comment below. I'm here to learn as much as to share. 🤝