Skip to content

django-ninja-crane

django-ninja-crane

Stripe-style API versioning for Django Ninja.

django-ninja-crane adds versioning and migrations to your Django Ninja APIs. When you change your API schemas, clients can keep using older versions, by transforming older api payloads before they reach your view.

The Problem

You've built an API. Users depend on it. Then you need to make a breaking change: restructuring what fields are where in the schema, changing the type of a field, ... .

Traditionally, you have a few (usually painful) options at this point:

  1. Run multiple versions of your application, putting the "old" version in a deprecation track.
  2. Make multiple NinjaAPI and/or router instances for each version, resulting in multiple views to maintain.

The Solution: API migrations!

Stripe already has a great solution to this problem:

  • Your code maintains the latest version of the API
  • Changes between API versions are described as migrations in code: how the schemas changed, and how to migrate payloads/responses between versions.
  • API users can stay on "their" preferred version of the API, with the migrations reshaping the request into a request of the latest version, and its response back into a response of the user's version.

Django Ninja Crane provides an easy-to-use implementation of this api versioning methodology, for Django apps using django-ninja.

It does this through automatic generation of migration files, tracking and describing what changed in your schemas since your last version. You only need to fill in the blanks: writing transformers describing how to "upgrade"/"downgrade" payloads/responses between api versions.

Versioning step by step

Making a new version in django ninja crane consists of the following steps:

  1. You make changes to your API schemas
  2. makeapimigrations auto-detects how your schemas/endpoints changed between versions and creates an api migration file, with "fill-in-the-blank" functions for you to write when breaking data changes are made.
  3. You fill in the blanks: writing transformer functions to handle upgrading/downgrading schema/endpoint data between versions
  4. At runtime, the versioning middleware uses the migration files and their transformation functions to turn a request into its shape for the latest version, and the api user receives a response in the shape of their older version.

uml diagram

Where to Start

New to django-ninja-crane? Start with the Quickstart to get up and running.

Need configuration details? See the Configuration Reference for all options.

Want to understand the design? Read How It Works for the architecture.

Status

django-ninja-crane is at early stages. This means there is a core, usable package available

  • API state extraction and delta detection
  • Migration file generation
  • Request/response transformation
  • Django middleware integration
  • Versioned OpenAPI schema generation

The public "API" (migration file syntax, middleware extension points, ninjaapi wrapping) should remain stable, but internals like how migration files are generated are still subject to change as the project evolves in supported features.

Next versions will focus on extending the scope of supported features: Covering discriminated unions, migrating auth, an interactive experience creating the migration file.