API versioning

[mbertrand]

What are the relevant tickets?

Addresses https://github.com/mitodl/hq/issues/5895

Description (What does it do?)

Creates a new library that uses transforms to transition between different API versions without needing to maintain completely separate serializers, views, etc for each.

See the README and RFC or more details.

How can this be tested?

A sample demo branch of mit-learn has been created to use this, and includes a few sample transforms.
Go to mitodl/mit-learn#3267 and follow the instructions there.

Additional Context

Something to consider as part of the review - do you think this approach is better or worse than creating separate serializers & views for each API version, as is currently done for mitxonline courses?

[Copilot]

Pull request overview

Introduces a new reusable mitol.api_versioning library that supports transform-based API versioning for Django REST Framework (and optional drf-spectacular schema rewriting), and wires it into the monorepo workspace/test app.

Changes:

• Added the api_versioning reusable app (transform registry, serializer mixin, schema hook, Django system checks, AppConfig autodiscovery).
• Added comprehensive pytest coverage for the new app.
• Updated workspace dependencies and lockfile; enabled the app in the testapp.

Reviewed changes

Copilot reviewed 19 out of 23 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
uv.lock	Adds the new workspace package and updates locked dependency metadata.
pyproject.toml	Adds mitol-django-api_versioning as a workspace dependency/source.
testapp/main/settings/shared.py	Enables mitol.api_versioning in the test Django project’s INSTALLED_APPS.
src/api_versioning/pyproject.toml	Defines the new distributable package metadata/build settings.
src/api_versioning/README.md	Documents the transform-based versioning approach and usage patterns.
src/api_versioning/CHANGELOG.md	Adds initial release changelog entry.
src/api_versioning/changelog.d/scriv.ini	Adds scriv configuration for the new package’s changelog workflow.
src/api_versioning/mitol/api_versioning/__init__.py	Declares distribution metadata/version and default app config.
src/api_versioning/mitol/api_versioning/apps.py	Adds AppConfig with autodiscovery of <app>.transforms modules.
src/api_versioning/mitol/api_versioning/checks.py	Adds Django system checks for transform configuration correctness.
src/api_versioning/mitol/api_versioning/mixins.py	Adds serializer mixin + raw-dict transform helper (including recursive nested support).
src/api_versioning/mitol/api_versioning/schema_hooks.py	Adds drf-spectacular postprocessing hook to version OpenAPI schemas.
src/api_versioning/mitol/api_versioning/transforms.py	Adds Transform base class + metaclass auto-registration and validation.
src/api_versioning/mitol/api_versioning/versions.py	Adds allowed-version utilities and the transform registry/query helpers.
src/api_versioning/mitol/api_versioning/py.typed	Marks the package as typed for type checkers.
src/api_versioning/mitol/api_versioning/settings/__init__.py	Placeholder settings package for future expansion.
tests/api_versioning/__init__.py	Initializes the new test package.
tests/api_versioning/conftest.py	Adds fixtures for registry isolation and version settings.
tests/api_versioning/test_checks.py	Tests for Django system checks behavior.
tests/api_versioning/test_mixins.py	Tests for serializer mixin behavior and recursive raw-dict transforms.
tests/api_versioning/test_schema_hooks.py	Tests for per-version schema postprocessing behavior.
tests/api_versioning/test_transforms.py	Tests for transform base behavior + metaclass registration/validation.
tests/api_versioning/test_versions.py	Tests for version registry and transform lookup ordering/filtering.

[Copilot]

Pull request overview

Introduces a new reusable mitol.api_versioning library to support transform-based API versioning (data + OpenAPI schema rewriting) without duplicating serializers/views per version, and wires it into the workspace/test app.

Changes:

• Added mitol.api_versioning app with transform registry, serializer mixin, schema postprocessing hook, system checks, and a management command.
• Added a full test suite for version registry behavior, transform auto-registration/validation, schema hook behavior, mixin behavior (including recursive dict transforms), and system checks.
• Updated workspace dependencies/lockfile and enabled the app in the included test Django project.

Reviewed changes

Copilot reviewed 20 out of 26 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
uv.lock	Adds the new workspace package and updates resolved dependency metadata.
pyproject.toml	Adds mitol-django-api_versioning as a workspace dependency/source.
testapp/main/settings/shared.py	Installs the new ApiVersioningApp in the test app.
src/api_versioning/pyproject.toml	Defines the new package’s build/dependency metadata.
src/api_versioning/README.md	Documents the API versioning approach, usage, and limitations.
src/api_versioning/CHANGELOG.md	Adds initial release entry.
src/api_versioning/changelog.d/scriv.ini	Adds scriv configuration for changelog entries.
src/api_versioning/mitol/api_versioning/init.py	Declares package metadata and default app config.
src/api_versioning/mitol/api_versioning/apps.py	Adds app config and transform autodiscovery in ready().
src/api_versioning/mitol/api_versioning/checks.py	Implements Django system checks for transform configuration.
src/api_versioning/mitol/api_versioning/management/init.py	Initializes management package.
src/api_versioning/mitol/api_versioning/management/commands/init.py	Initializes commands package.
src/api_versioning/mitol/api_versioning/management/commands/check_api_transforms.py	Adds a convenience command wrapping manage.py check --tag api_versioning.
src/api_versioning/mitol/api_versioning/mixins.py	Adds VersionedSerializerMixin and transform_dict_backwards (incl. recursive nested transforms).
src/api_versioning/mitol/api_versioning/schema_hooks.py	Adds drf-spectacular postprocessing hook for per-version schema rewriting.
src/api_versioning/mitol/api_versioning/transforms.py	Adds Transform base class + metaclass auto-registration and validation.
src/api_versioning/mitol/api_versioning/versions.py	Adds registry utilities and transform lookup logic between versions.
src/api_versioning/mitol/api_versioning/py.typed	Marks package as typed.
tests/api_versioning/init.py	Initializes api_versioning test package.
tests/api_versioning/conftest.py	Adds fixtures for version settings and registry isolation.
tests/api_versioning/test_checks.py	Tests system checks (E001/W001/E002).
tests/api_versioning/test_mixins.py	Tests serializer mixin behavior and recursive dict transforms.
tests/api_versioning/test_schema_hooks.py	Tests schema hook behavior and schema-name resolution helpers.
tests/api_versioning/test_transforms.py	Tests Transform base defaults, metaclass registration, and validation.
tests/api_versioning/test_versions.py	Tests registry APIs and ordering/filtering semantics.