django-ninja-crane
Stripe-style API versioning and migrations for Django Ninja.
django-ninja-crane enables you to:
- Track API schema changes over time via migration files
- Automatically transform requests/responses between API versions
- Serve older API versions to clients while running only your latest code
For more information, check the documentation
Installation
pip install django-ninja-crane
Requirements:
- Python 3.12+
- Django 6.0+
- Django Ninja 1.5.1+
Quick Start
1. Create a Versioned API
Replace any NinjaAPI instances you want to version with VersionedNinjaAPI:
# urls.py
from crane import VersionedNinjaAPI
from myapp.api import router
api = VersionedNinjaAPI(api_label="default", app_label="myapp")
api.add_router("/persons", router)
urlpatterns = [
path("api/", api.urls),
]
2. Add the Middleware
# settings.py
INSTALLED_APPS = [
# ...
"crane",
]
MIDDLEWARE = [
# ...
"crane.middleware.VersionedAPIMiddleware",
]
3. Save Your Initial API State
Create the first migration to capture your current API as version 1:
python manage.py makeapimigrations myapp.default --name "initial"
This creates myapp/api_migrations/default/m_0001_initial.py which records your API's starting state.
4. Make Changes to Your API
Now modify your API schemas. For example, add a phone field to PersonOut:
class PersonOut(Schema):
id: int
name: str
email: str
phone: str | None = None # New field
5. Create a Migration for the Changes
Generate a migration that captures the difference between your saved state and the current API:
python manage.py makeapimigrations myapp.default --name "add_phone_field"
This generates myapp/api_migrations/default/m_0002_add_phone_field.py containing:
- Schema changes (added/removed/modified fields)
- Operation changes (new endpoints, modified parameters)
6. Implement Data Transformers
The generated migration includes skeleton transformer functions. For simple cases (adding optional fields, removing fields), the generator creates working implementations automatically:
# myapp/api_migrations/default/m_0002_add_phone_field.py (generated)
def downgrade_person_out(data: dict) -> dict:
"""2 -> 1: Transform person_out for older clients."""
data.pop("phone", None)
return data
def upgrade_person_in(data: dict) -> dict:
"""1 -> 2: Transform person_in from older clients."""
data.setdefault("phone", None)
return data
For changes that require manual intervention (e.g., adding required fields, breaking schema changes), the generator
creates functions that raise NotImplementedError:
def upgrade_user(data: dict) -> dict:
"""1 -> 2: Transform user from older clients."""
raise NotImplementedError("Provide default value for new field: email")
# data.setdefault("email", <default_value>)
Replace these with actual implementations before deploying. The validateapimigrations command can check for any
remaining NotImplementedError calls.
Now clients requesting X-API-Version: 1 will receive responses without the phone field, while your code only handles
the latest version.
Development
# Install dependencies
uv sync
# Run tests
uv run pytest
# Lint & format
uv run ruff check .
uv run ruff format .
# Run dev server
uv run python manage.py runserver
Current functionality
The current functionality covers most common API migration changes:
- adding/removing new schemas
- modifying schema contents
- modifying operation input parameters
Limitations
- union fields (AnyOf), discriminated unions are covered by running all transformers of a union when any of the types in the union are updated.
- If you remove an endpoint, you need to manually set up a path rewrite pointing it to the new operation to use for that request.
What's next?
- Proper support for discriminated unions
- Management command to remove an old version
- Easier interface for "bring your own version resolver", allowing you to e.g., determine the version from the request's user.
- Validation to check whether your defined data migrations cover the schema changes
- Interactive makeapimigrations, prompting whether you want operation or schema migrations for schema changes.
Metadata
Release files for django-ninja-crane 0.1.11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_ninja_crane-0.1.11.tar.gz | 37.3 kB | Without provenance | Details for django_ninja_crane-0.1.11.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_ninja_crane-0.1.11-py3-none-any.whl | Python 3 | none | any | Details for django_ninja_crane-0.1.11-py3-none-any.whl |
Total release size: 84.4 kB
Release files / django_ninja_crane-0.1.11.tar.gz
| Download URL | django_ninja_crane-0.1.11.tar.gz |
|---|---|
| Size | 37.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2f59e731a831aea7d711f4840c52d7f15073c7f602b2d49a6eb11031c817f508
|
|
BLAKE2b-256 checksum How to use checksums |
b88f491f7d27dda649ced73dde7fd27aa525d0023293adeb1b95184045c98038
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / django_ninja_crane-0.1.11-py3-none-any.whl
| Download URL | django_ninja_crane-0.1.11-py3-none-any.whl |
|---|---|
| Size | 47.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b7f090a0df302d3f0dd0515b4001ac3c3c31246bfecb67814a2c827aab662520
|
|
BLAKE2b-256 checksum How to use checksums |
9c159b985b4bccbc083f5050dd642d50fabc3636f45d3c773eaf92e7a492d718
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for django-ninja-crane 0.1.11
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.