Django backend API

This page is only the entry point for the Django backend API. Endpoint paths, request parameters, response structures, authentication schemes, and schema details are generated from OpenAPI and are no longer maintained as handwritten per-endpoint copies under docs/.

Generated documentation

After starting the Django backend in a local development environment, use:

Purpose	URL
Swagger UI	http://localhost:8000/api/docs/
Redoc	http://localhost:8000/api/redoc/
OpenAPI schema	http://localhost:8000/api/schema/

The backend currently exposes these documentation routes only when DJANGO_DEBUG=true. Whether they are available in staging or production is a deployment decision. If the backend is published through a reverse proxy, use the same paths on that environment's origin.

Usage conventions

• The business API prefix is /api/v1/.
• The web admin client primarily uses CookieJWTAuthentication; Authorization: Bearer <token> is also supported.
• Signage device endpoints use a separate device Bearer token.
• Long-running import endpoints return a task_id; task status is queried through /api/v1/tasks/{id}/.
• Use Swagger UI or Redoc for concrete fields, enums, pagination parameters, upload formats, and response schemas.

Maintenance boundary

docs/ continues to document architecture, business flows, permission models, deployment, and integration notes. API facts are generated from backend serializers, views, and drf-spectacular annotations.

When adding or changing an API, update the schema information in code first and verify:

DJANGO_DEBUG=true ../.venv/bin/python manage.py spectacular --validate --file /tmp/myucspace-openapi.yaml

The generated OpenAPI file must remain usable. Generation errors must be fixed; warnings should be cleaned up according to their impact.