Django-AWS-API-Gateway-WebSockets¶
Django-AWS-API-Gateway-WebSockets helps Django projects receive and send messages over AWS API Gateway WebSocket APIs.
It provides Django models, views, mixins, queryset helpers, admin actions, and management commands for working with WebSocket connections backed by AWS API Gateway.
The package is designed to make it easier to:
receive WebSocket messages in Django class-based views;
send a message back to the current connection;
send messages to all active sessions in a channel;
multicast or broadcast messages to groups of connected clients;
maintain WebSocket session state in your Django database;
create and manage API Gateway resources from Django.
Documentation map¶
If you are new to the project, start with:
Quickstart for the shortest path to a working setup;
Concepts for the main terms used by the package;
Installation for installation steps;
Configuration and Settings for Django and AWS configuration.
If you are setting up AWS, read:
AWS IAM Setup for IAM permissions;
API Gateway Setup for creating the API Gateway;
Adding new routes for custom WebSocket routes;
Django Admin for managing API Gateway records through Django Admin.
If you are building a frontend client, read:
Client integration for browser connection patterns;
Using reconnecting-websocket for reconnecting client behaviour;
WebSocket tokens for authenticated WebSocket connections;
Templates and mixins for adding WebSocket context to Django templates.
If you are sending messages from Django, read:
Message patterns for unicast, multicast, broadcast, toasts, and task progress examples;
Reference for the models used to track sessions and send messages;
Full chat room example for a complete chat room example.
If you are preparing for production, read:
Security for the security model;
Permissions for Django permission checks;
Rate limiting for connection and token rate limits;
Deployment for production deployment guidance;
Clean-up for scheduled cleanup tasks;
Troubleshooting for common problems.
If you are contributing or maintaining the project, read:
Testing for testing guidance;
Contributing for contribution instructions;
Upgrade guide for upgrade considerations;
Release process for release steps;
Architecture for the project architecture.
Getting started¶
Getting started
- Exposition
- Quickstart
- Before you start
- Install the package
- Add the app
- Run migrations
- Configure AWS access
- Create a WebSocket view
- Add the URL route
- Create an API Gateway record
- Create the API Gateway in AWS
- Create the custom domain
- Configure DNS
- Connect from a browser
- Using reconnecting-websocket
- Using WebSocket tokens
- Send to all clients in a channel
- Send to all connected clients
- Clean up old records
- Troubleshooting
- Next steps
- Concepts
- Overview
- API Gateway
- WebSocket API
- Route
- Route key
- Route selection expression
- Action
- Handler
- Handler selection key
- Target base endpoint
- Connection ID
- WebSocket session
- Channel
- Channels are not authorization
- WebSocket token
- Unicast
- Multicast
- Broadcast
- API Gateway record
- Additional route
- Stage
- Custom domain
- Putting the concepts together
- Common confusion
- Related pages
- Installation
- Compatibility
- Supported Python versions
- Supported Django versions
- Recommended versions
- Compatibility matrix
- Django 5.0
- Django 6.0
- Python 3.14 and 3.15
- AWS compatibility
- AWS credentials
- Browser compatibility
- Documentation build compatibility
- Package dependencies
- Testing compatibility
- Upgrade guidance
- Support policy
- Related pages
- Configuration
- Settings
AWS setup¶
AWS setup
- AWS IAM Setup
- API Gateway Setup
- Before you start
- How the API Gateway integration works
- Create the Django URL route
- Create the WebSocket view
- Route selection
- Create the API Gateway record
- Create the API Gateway using Django Admin
- Create the API Gateway using a management command
- Set up a custom domain
- Configure DNS
- Configure cookies for subdomains
- Connect from the browser
- Adding additional routes
- Testing the setup
- Troubleshooting
- Next steps
- Adding new routes
Usage¶
Usage
- Client integration
- Overview
- Basic connection
- WebSocket URL format
- Channels
- WebSocket tokens
- Requesting a token
- Connecting with a token
- Message payloads
- Handler selection
- Receiving messages
- Sending messages safely
- Changing channels
- Reconnect handling
- Client-side validation
- Example complete client
- Security recommendations
- Related pages
- Using reconnecting-websocket
- Templates and mixins
- Message patterns
- Overview
- Message shape
- Recommended message fields
- Reply to the current connection
- Send to one stored session
- Send to a user’s active sessions
- Send to a channel
- Broadcast to all connected sessions
- Send a toast notification
- Send task progress
- Send lightweight invalidation messages
- Chat room message
- Admin broadcast
- Message size limits
- Handling stale connections
- Security considerations
- Recommended message conventions
- Testing message patterns
- Related pages
- Full chat room example
- Overview
- Example assumptions
- Django model
- Django WebSocket view
- URL route
- API Gateway target endpoint
- HTML client
- How fetching history works
- How broadcasting to the current room works
- How changing rooms works
- Broadcasting to all channels from the Django shell
- Broadcasting to one room from the Django shell
- Using WebSocket tokens
- Security notes
- Related pages
- Management Commands
- Clean-up
Security and operations¶
Security and operations
- Security
- Security model
- Security model
- OWASP Top 10 alignment
- WebSocket token protection
- CSRF considerations
- Rate limiting
- API Gateway validation
- Header validation
- Origin and host checks
- Connection ID validation
- Channel name validation
- Request body validation
- Message size validation
- Handler whitelisting
- Django permissions
- Authentication recommendations
- IAM security
- Cookie and subdomain security
- Cleanup and stale sessions
- Operational logging
- Error handling
- Production checklist
- Reporting vulnerabilities
- Related pages
- WebSocket tokens
- Why WebSocket tokens are needed
- Token properties
- Default behaviour
- Token request endpoint
- Requesting a token from the browser
- Opening the WebSocket connection
- Using reconnecting clients
- Token expiry
- Single-use behaviour
- Session binding
- Authentication
- Disabling WebSocket tokens
- Custom token endpoints
- Token generation rate limiting
- Cleaning up tokens
- Troubleshooting
- Production recommendations
- Related pages
- Permissions
- Overview
- Authentication first
- Require any permission
- Require all permissions
- Combining permission options
- Object-level permissions
- Handler whitelisting
- Creating Django permissions
- Checking permissions manually
- Per-handler permissions
- Channels and permissions
- Recommended patterns
- Example: chat room permissions
- Common mistakes
- Testing permissions
- Production checklist
- Related pages
- Rate limiting
- Deployment
- Deployment overview
- Typical architecture
- Production checklist
- Django settings
- AWS credentials
- API Gateway deployment
- Custom domains
- DNS
- WebSocket tokens in production
- Rate limiting
- Permissions
- Client reconnect strategy
- Scheduled cleanup
- Logging and monitoring
- Database considerations
- Environment separation
- Rolling deployments
- Blue/green and multi-instance deployments
- Deployment smoke test
- Troubleshooting
- Related pages
- Local development
- Overview
- Common local setup
- Basic local development steps
- Start Django locally
- Start a tunnel
- Update the API Gateway target endpoint
- Allow the tunnel host in Django
- CSRF trusted origins
- Local AWS credentials
- Create a local API Gateway record
- Create or update the API Gateway
- If your tunnel URL changes
- Connecting from the browser
- Testing without WebSocket tokens
- Testing with WebSocket tokens
- Debugging local requests
- Header differences with tunnels
- Common local issues
- Recommended local workflow
- Local cleanup
- Security reminders
- Related pages
- Troubleshooting
- General checklist
- Connection fails immediately
- Django returns bad request
- Messages always go to the default handler
- Custom route is not called
- WebSocket token request fails
- WebSocket token is rejected during connection
- Rate limit exceeded
- User is anonymous unexpectedly
- Permission denied
- Messages are not received by the browser
- GoneException when sending messages
- Messages fail because they are too large
- Local development does not work
- Custom domain does not work
- API Gateway creation fails
- Management command cannot send or create resources
- Debugging WebSocket views
- Cleanup problems
- Getting more information
- Related pages
- Testing
- Testing strategy
- Run the project tests
- Testing WebSocket views as Django views
- API Gateway test headers
- Testing a message handler
- Testing connection handling
- Testing disconnection
- Testing handler selection
- Testing permissions
- Testing WebSocket tokens
- Testing rate limiting
- Mocking message sending
- Testing broadcast behaviour
- Testing stale connections
- Testing management commands
- Testing API Gateway creation
- Testing client JavaScript
- Test data cleanup
- Recommended test coverage
- Testing tips
- Related pages
- Upgrade guide
- Before upgrading
- Recommended upgrade process
- Upgrade checklist
- Upgrading from pre-token versions
- Upgrading reconnecting clients
- Upgrading for rate limiting
- Upgrading for permission checks
- Upgrading handler selection
- Upgrading custom routes
- Upgrading cleanup tasks
- Upgrading AWS configuration
- Upgrading Django settings
- Upgrading tests
- Staging validation
- Production rollout
- Rollback considerations
- Common upgrade problems
- Recommended upgrade path
- Related pages
Project¶
Project
- Architecture
- High-level architecture
- Architecture diagram
- Core request flow
- Django URL routing
- AWS API Gateway routes
- WebSocketView
- Connection flow
- Message handling flow
- Disconnection flow
- Security architecture
- Messaging patterns
- Database models
- Admin and management commands
- Operational considerations
- Configuration example
- Related pages
- Contributing
- Release process
- Overview
- Before starting
- Check the current version
- Use semantic versioning
- Update the version
- Update the changelog
- Run formatting and pre-commit checks
- Run tests
- Build the documentation locally
- Build the package
- Check the package
- Inspect the package contents
- Test publish if needed
- Publishing to PyPI
- Create a Git commit
- Create a Git tag
- Create a GitHub release
- Confirm Read the Docs build
- Post-release checks
- Start the next development cycle
- Release checklist
- Cleaning old build artifacts
- Common release problems
- Related pages
- FAQ
- License
- Changelog
- 4.* - Future Release - Breaking changes
- 3.0.4 - 28th May 2026 - Renamed the WebSocketToken and RateLimit table names
- 3.0.3 - 28th May 2026 - Django 5.2 MySQL Index bug Fix (Yanked)
- 3.0.2 - 28th May 2026 - Django 5.2 MySQL Index bug Fix (Yanked)
- 3.0.1 - 1st May 2026 - Security release - Breaking changes
- 3.0.0 - 1st May 2026 - Security release - Breaking changes
- 2.2.2 - 26th March 2026
- 2.2.1 - 18th March 2026
- 2.2.0 - 23rd February 2026
- 2.1.1 - 20th February 2026
- 2.1.0 - 12th February 2026
- 2.0.2 - 30th September 2025
- 2.0.1 - 30th September 2025
- 2.0.0 - 30th September 2025 - Yanked
- 1.4.1 - 8th June 2025
- 1.4.0 - 8th June 2025
- 1.3.0 - 26th May 2025
- 1.2.1 - 12th May 2025
- 1.2.0 - 12th May 2025 - yanked
- 1.1.3 - 7th May 2025
- 1.1.2 - 17th March 2025
- 1.1.1 - 20th November 2024
- 1.1.0 - 19th November 2024
- 1.0.22 - 21st October 2024
- 1.0.21 - 4th August 2024
- 1.0.20 - 15th July 2024
- 1.0.19 - 11th July 2024
- 1.0.17 - 28th May 2024
- 1.0.16 - 24th May 2024
- 1.0.15 - 7th May 2024
- 1.0.14 - 7th May 2024
- 1.0.13 - 14th December 2023
- 1.0.12 - 20th September 2023
- 1.0.11 - 18th January 2023
- 1.0.10 - 15th December 2022
- 1.0.9 - 12th December 2022
- 1.0.8 - 9th December 2022
- 1.0.7 - 9th December 2022
- 1.0.6 - 9th December 2022
- 1.0.0 - 1.0.5 - 8th December 2022
- 0.2.2 - 20th September 2022
- 0.2.1 - 13th September 2022
- 0.2.0 - 12th September 2022
- 0.1.5 - 4th August 2022
- 0.1.4 - 4th August 2022
- 0.1.3 - 4th August 2022
- 0.1.2 - 29th June 2022
- 0.1.0 - 8th June 2022
- 0.0.1 - 17th Jan 2022
API reference¶
API reference