Django REST API Pro

What's Included

Django REST API Pro is an enterprise-grade REST API boilerplate built with Django 5.1+ and Django REST Framework. It includes multi-auth (JWT, API Keys, OAuth2, 2FA), role-based access control, versioned endpoints, webhooks, audit logging, rate limiting, and health checks.

Requirements

Quick Start

1. Extract & Install

cd django-rest-api-pro
cp .env.example .env
python -m venv venv && source venv/bin/activate
pip install -r requirements/development.txt

2. Database Setup

python manage.py migrate
python manage.py createsuperuser
python manage.py seed_data  # optional sample data

3. Run

python manage.py runserver

Visit http://127.0.0.1:8000/api/docs/ for interactive Swagger UI.

Authentication

Four authentication methods, one unified permission layer.

JWT Tokens (Default)

# Login to get tokens
curl -X POST /api/v1/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}'

# Use access token
curl /api/v1/resources/ \
  -H "Authorization: Bearer <access_token>"

# Refresh when expired
curl -X POST /api/v1/auth/refresh/ \
  -d '{"refresh": "<refresh_token>"}'

API Keys

# Create an API key (requires JWT auth)
curl -X POST /api/v1/auth/api-keys/ \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "My Integration"}'

# Use API key
curl /api/v1/resources/ \
  -H "X-API-Key: <full_key>"

OAuth2 (Google & GitHub)

Configure provider credentials in .env and redirect users to:

/api/v1/auth/oauth/google/
/api/v1/auth/oauth/github/

Two-Factor Authentication (TOTP)

POST /api/v1/auth/2fa/setup/    # Get QR code URI
POST /api/v1/auth/2fa/verify/   # Verify & enable
POST /api/v1/auth/2fa/disable/  # Disable

API Endpoints

Authentication

Resources (v1)

Resources (v2)

Webhooks

Health

Rate Limiting

Dynamic per-user, per-auth-type rate limiting with configurable tiers.

Response Headers

X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1985
X-RateLimit-Reset: 1616169600

Custom Limits

Override defaults in .env:

RATE_LIMIT_ANON=200/hour
RATE_LIMIT_USER=5000/hour
RATE_LIMIT_API_KEY=10000/hour

Webhooks

Event-driven webhook system with HMAC signing and automatic retries.

Register a Webhook

curl -X POST /api/v1/webhooks/endpoints/ \
  -H "Authorization: Bearer <token>" \
  -d '{
    "url": "https://your-app.com/webhook",
    "secret": "your-secret",
    "events": ["resource.created", "resource.updated", "resource.deleted"]
  }'

Payload Format

{
  "event": "resource.created",
  "timestamp": "2026-03-25T12:00:00Z",
  "data": {
    "id": "res_abc123",
    "name": "My Resource",
    "status": "active"
  }
}

Signature Verification

Every delivery includes an X-Webhook-Signature header — HMAC-SHA256 of the JSON payload signed with your secret.

import hmac, hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Retry Policy

Failed deliveries retry with exponential backoff: 1m, 2m, 4m, 8m, 16m (max 5 retries).

Health Checks

Built-in health monitoring endpoints for uptime and observability.

Response Example

{
  "status": "healthy",
  "database": "ok",
  "redis": "ok",
  "celery": "ok",
  "timestamp": "2026-03-25T12:00:00Z"
}

Role-Based Access Control (RBAC)

• Custom roles with granular permissions per endpoint
• Organization-level and project-level scoping
• Built-in roles: Admin, Editor, Viewer
• Easy to add custom roles

Project Structure

django-rest-api-pro/
  apps/
    accounts/        # Users, organizations, profiles
    authentication/  # JWT, API keys, OAuth2, 2FA
    api_v1/          # Version 1 endpoints
    api_v2/          # Version 2 endpoints
    webhooks/        # Outbound webhook system
    audit/           # Audit trail logging
    health/          # Health check endpoints
    core/            # Shared utilities & base classes
  config/
    settings/        # Split settings (base/dev/prod/test)
    celery.py        # Celery task queue config
  tests/             # 95%+ test coverage
  docker/            # Docker & docker-compose
  docs/              # Full documentation

Deployment

Docker (Recommended)

docker compose -f docker-compose.yml up --build -d

Production Checklist

• DEBUG=False
• Strong SECRET_KEY
• PostgreSQL configured
• Redis configured
• HTTPS enabled (SECURE_SSL_REDIRECT=True)
• Sentry DSN set
• Celery workers running
• Rate limits tuned
• Audit log retention configured

Settings

Split settings for different environments:

• config/settings/base.py — shared settings
• config/settings/development.py — local dev
• config/settings/production.py — production
• config/settings/testing.py — test runner

Set via environment variable:

DJANGO_SETTINGS_MODULE=config.settings.production

Management Commands

Live Demo

Try the live demo at djz.djangozen.com/rest-api-pro/

• Swagger UI: /api/docs/
• ReDoc: /api/redoc/
• Health Check: /health/full/

Support

• Documentation: This page + /docs/ folder in the project
• Support: djangozen.com/support/ (48h response)
• Updates: 12 months free updates included