Documentation - Django REST API Pro

Quick Start

Get up and running in under 5 minutes.

# Clone and setup
git clone <your-repo> && cd django-rest-api-pro
cp .env.example .env
python -m venv venv && source venv/bin/activate
pip install -r requirements/development.txt

# Database & run
python manage.py migrate
python manage.py createsuperuser
python manage.py seed_data  # optional sample data
python manage.py runserver
          

Visit /api/docs/ for interactive Swagger UI or /api/redoc/ for ReDoc.

API Reference

Authentication Endpoints

Method	Endpoint	Description
POST	`/api/v1/auth/register/`	Register new user
POST	`/api/v1/auth/login/`	Get JWT tokens
POST	`/api/v1/auth/refresh/`	Refresh JWT token
GET	`/api/v1/auth/profile/`	Get current user profile
POST	`/api/v1/auth/api-keys/`	Create API key
GET	`/api/v1/auth/api-keys/`	List API keys
POST	`/api/v1/auth/2fa/setup/`	Setup 2FA (TOTP)
POST	`/api/v1/auth/2fa/verify/`	Verify 2FA code

Resource Endpoints (v1)

Method	Endpoint	Description
GET	`/api/v1/resources/`	List resources (paginated, filterable)
POST	`/api/v1/resources/`	Create resource
GET	`/api/v1/resources/{slug}/`	Get resource detail
PUT	`/api/v1/resources/{slug}/`	Update resource
DELETE	`/api/v1/resources/{slug}/`	Delete resource
POST	`/api/v1/resources/bulk_create/`	Bulk create resources
DELETE	`/api/v1/resources/bulk_delete/`	Bulk delete resources

Webhook Endpoints

Method	Endpoint	Description
GET	`/api/v1/webhooks/endpoints/`	List registered webhooks
POST	`/api/v1/webhooks/endpoints/`	Register webhook URL
GET	`/api/v1/webhooks/deliveries/`	View delivery logs

Authentication

Four authentication methods, one unified permission layer.

1. 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>"}'
          

2. 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>"
          

3. OAuth2 (Google & GitHub)

Configure provider credentials in .env and redirect users to:

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

4. Two-Factor Authentication (TOTP)

# Setup - returns QR code URI
curl -X POST /api/v1/auth/2fa/setup/ \
  -H "Authorization: Bearer <token>"

# Verify with code from authenticator app
curl -X POST /api/v1/auth/2fa/verify/ \
  -d '{"code": "123456"}'

# Disable 2FA
curl -X POST /api/v1/auth/2fa/disable/
          

Rate Limiting

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

Auth Type	Rate	Burst
Anonymous	100 / hour	30 / minute
JWT User	2,000 / hour	30 / minute
API Key (Standard)	5,000 / hour	30 / minute
API Key (Premium)	50,000 / hour	30 / minute

Response Headers

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

Custom Limits

Override defaults in your .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 with an HMAC-SHA256 hash of the JSON payload signed with your secret.

# Python verification example
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

1 min 2 min 4 min 8 min 16 min (max 5 retries, exponential backoff)

Health Checks

Built-in health monitoring endpoints for uptime and observability.

Endpoint	Checks	Use Case
`/health/`	App is running	Load balancer ping
`/health/db/`	Database connection	DB monitoring
`/health/redis/`	Redis connection	Cache monitoring
`/health/full/`	All systems	Full status page

Response Example

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

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

Sentry DSN set

Celery workers running

Rate limits tuned

Audit log retention

API docs protected

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
          