Django AWS API Gateway WebSockets

Django AWS API Gateway WebSockets lets Django projects use AWS API Gateway WebSocket APIs without running a dedicated WebSocket server.

AWS API Gateway manages the WebSocket connection. Django receives API Gateway events as normal HTTP requests and can send messages back to connected clients through the AWS API Gateway Management API.

This project is designed for Django applications that want WebSocket-style features while keeping a traditional Django request/response deployment model.

Documentation

Full documentation is available on Read the Docs:

https://django-aws-api-gateway-websockets.readthedocs.io/

Useful starting points:

• Quickstart
• Concepts
• API Gateway setup
• Client integration
• Security
• WebSocket tokens
• Deployment
• Troubleshooting

Features

• Handle AWS API Gateway WebSocket events with Django class-based views.
• Track WebSocket connections in the Django database.
• Associate connections with Django users where available.
• Group connections using channels.
• Send messages to:
  • one connection;
  • all connections for a user;
  • all connections in a channel;
  • all connected clients.
• Create and manage API Gateway resources from Django Admin or management commands.
• Add custom API Gateway routes for different Django views.
• Use WebSocket tokens for authenticated connection protection.
• Rate limit WebSocket connection attempts.
• Restrict handlers using Django permissions.
• Use mixins to add WebSocket connection details to template context.

When to use this package

Use this package if you want:

• AWS API Gateway to manage WebSocket connections;
• Django to receive WebSocket events as HTTP requests;
• to avoid running a dedicated ASGI WebSocket server;
• to send messages from Django to connected browser clients;
• to group connections into channels for multicast messaging;
• to integrate WebSocket behaviour with existing Django models, views, admin, permissions, and management commands.

This package is not a replacement for Django Channels. Django Channels is a better fit if you want Django itself to run an ASGI WebSocket server.

Requirements

• Python 3.10+
• Django 5.2+
• AWS account with API Gateway permissions
• Boto3-compatible AWS credentials or IAM role

See the installation guide and AWS IAM setup guide for details.

Installation

Install from PyPI:

pip install django-aws-api-gateway-websockets

Add the app to INSTALLED_APPS:

INSTALLED_APPS += ["django-aws-api-gateway-websockets"]

Run migrations:

python manage.py migrate

See the full quickstart for a working example.

Minimal example

Add a Django URL route with a route slug:

from django.urls import path

from .views import ExampleWebSocketView

urlpatterns = [
    path(
        "ws/<slug:route>",
        ExampleWebSocketView.as_view(),
        name="example_websocket",
    ),
]

Create a WebSocket view:

from django.http import JsonResponse
from django_aws_api_gateway_websockets.views import WebSocketView


class ExampleWebSocketView(WebSocketView):
    def default(self, request, *args, **kwargs):
        self.websocket_session.send_message({})
        return JsonResponse({"ok": True})

Create a WebSocket view:

from django.http import JsonResponse

from django_aws_api_gateway_websockets.views import WebSocketView


class ExampleWebSocketView(WebSocketView):
    def default(self, request, *args, **kwargs):
        self.websocket_session.send_message(
            {
                "type": "reply",
                "message": "Hello from Django",
            }
        )

        return JsonResponse({"ok": True})

Connect from the browser:

const socket = new WebSocket("wss://ws.example.com?channel=example");

socket.onmessage = function (event) {
    const message = JSON.parse(event.data);
    console.log("Received:", message);
};

socket.onopen = function () {
    socket.send(JSON.stringify({
        action: "default",
        message: "Hello from the browser"
    }));
};

For production usage, read the documentation on WebSocket tokens and security.

AWS setup

The package can create and configure API Gateway WebSocket resources using Django Admin actions or management commands. Typical setup steps:

1. Configure AWS credentials or an IAM role.
2. Create an record. ApiGateway
3. Create the AWS API Gateway.
4. Optionally create a custom domain.
5. Configure DNS.
6. Connect from your frontend client.

See the full API Gateway setup guide.

Management commands

The package includes management commands for API Gateway setup and cleanup.

python manage.py createApiGateway --pk=<api_gateway_pk>
python manage.py createCustomDomain --pk=<api_gateway_pk>
python manage.py clearWebSocketSessions
python manage.py cleanupWebSocketTokens

See the management commands documentation for details.

Security

Version 3.0.0 introduced significant security improvements, including:

• WebSocket token protection;
• single-use session-bound connection tokens;
• connection attempt rate limiting;
• handler whitelisting;
• Django permission checks;
• stricter input validation;
• channel name validation;
• message size validation;
• safer debug output;
• audit logging for admin actions.

For authenticated production WebSocket endpoints, read:

• Security
• WebSocket tokens
• Permissions
• Rate limiting

To report a vulnerability, see SECURITY.md.

Development

Clone the repository:

git clone https://github.com/StevenMapes/django-aws-api-gateway-websockets.git
cd django-aws-api-gateway-websockets

Install development requirements into your virtual environment. Run tests:

pip install pytest-django
coverage erase
python -W error::DeprecationWarning -W error::PendingDeprecationWarning -m coverage run --parallel -m pytest --ds tests.settings
coverage combine
coverage report

Build the documentation locally:

cd docs
pip install -r requirements.txt
make html

See the contributing guide for more information.

Changelog

See the changelog for release history.

License

This project is licensed under the MIT License. See LICENSE.