Skip to main content
django-ninja-crane

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)

Source distribution for django-ninja-crane 0.1.11
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)

Table of built distributions (wheels) for django-ninja-crane 0.1.11
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page