# Add API Versioning to a Django REST Framework Project from a Linear Issue

Yes. An agent moves your DRF routes under /api/v1/ with NamespaceVersioning, updates every reverse() in the tests and the README, runs the suite, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-api-versioning/django-rest-framework/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the URL tree is built before it adds a version. In a project shaped like HackSoftware/Django-Styleguide-Example, `config/urls.py` includes `styleguide_example.api.urls` under `api/` with the namespace `api`, and `styleguide_example/api/urls.py` includes `authentication`, `users`, `errors`, `files` and `google-oauth2`, each with its own namespace; `authentication/urls.py` nests `session` and `jwt` namespaces another level down. `REST_FRAMEWORK` in `config/django/base.py` sets an exception handler and a filter backend and no versioning class. Every URL is reached by name: `test_user_login.py` calls `reverse("api:authentication:session:login")`, `reverse("api:authentication:jwt:login")` and `reverse("api:authentication:me")`, and `files/utils.py` builds the local upload URL with `reverse("api:files:upload:direct:local")`. `README.md` documents the paths as `/api/auth/jwt/login/` and `/api/users/`, and `.github/workflows/django.yml` runs `ruff check`, `mypy --config mypy.ini styleguide_example/` and `pytest` against a Postgres service.

It picks the scheme that fits a project built on namespaces. `REST_FRAMEWORK` gains `DEFAULT_VERSIONING_CLASS` set to `rest_framework.versioning.NamespaceVersioning`, `ALLOWED_VERSIONS` of `["v1"]` and `DEFAULT_VERSION` of `v1`. In `config/urls.py` the include moves to `api/v1/` with the namespace `v1` in place of `api`, so a request to `/api/v1/users/` resolves inside the `v1:users` namespace and DRF reads `request.version` as `v1` from the first namespace segment that is an allowed version. Nothing in `styleguide_example/api/urls.py` or the app-level `urls.py` files changes, because they only know their own namespace. The `api/` prefix with no version is dropped rather than aliased, since DRF would answer it with the invalid-version error, and the README's path list is updated in the same commit.

Every `reverse()` follows the rename: the six calls in `styleguide_example/authentication/tests/apis/test_user_login.py` become `v1:authentication:...`, and `styleguide_example/files/utils.py` becomes `v1:files:upload:direct:local`. The agent also adds a `styleguide_example/api/tests/test_versioning.py` that fetches `/api/v1/users/` with `APIClient` and asserts `200`, fetches `/api/users/` and asserts `404`, and uses a tiny `APIView` subclass under a test-only URL to assert that `request.version` is `v1`, so the setting is covered rather than assumed. Where an API should behave differently in a later version, the pattern is `if request.version == "v2"` inside the view, and the agent writes that in a short section of `README.md` without inventing a `v2`.

Before it pushes, the agent runs what `django.yml` runs: `ruff check .`, `mypy --config mypy.ini styleguide_example/` and `pytest` with `config.django.test`, against a Postgres it starts in the sandbox with the `DATABASE_URL` the Compose file uses. It also starts the server and requests `/api/v1/auth/me/` and `/api/auth/me/` with `curl` to show the first answers `403` for an anonymous user, as `ApiAuthMixin` requires, and the second answers `404`, and pastes both in the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add API versioning to this Django REST Framework project and open a pull request. Read config/urls.py, config/django/base.py, styleguide_example/api/urls.py, styleguide_example/authentication/urls.py, styleguide_example/authentication/tests/apis/test_user_login.py, styleguide_example/files/utils.py, README.md and .github/workflows/django.yml first. Set DEFAULT_VERSIONING_CLASS to rest_framework.versioning.NamespaceVersioning with ALLOWED_VERSIONS v1 and DEFAULT_VERSION v1 in REST_FRAMEWORK. Move the api include in config/urls.py to api/v1/ with the namespace v1 and drop the unversioned api/ prefix. Update every reverse() that starts with api: to v1:, including files/utils.py, and update the paths in README.md. Add styleguide_example/api/tests/test_versioning.py asserting /api/v1/users/ answers 200, /api/users/ answers 404 and request.version is v1 in a view. Add a short README section on branching on request.version for a future v2 without creating one. Run ruff check ., mypy --config mypy.ini styleguide_example/ and pytest against a Postgres as the workflow does, start the server and curl /api/v1/auth/me/ and /api/auth/me/, and paste the output in the pull request. Do not change any API's behaviour or any app-level urls.py.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `config/django/base.py` (three keys in `REST_FRAMEWORK`), `config/urls.py` (the `api/v1/` include with namespace `v1`), `styleguide_example/authentication/tests/apis/test_user_login.py` and `styleguide_example/files/utils.py` (the `reverse()` names), `README.md`, and adds `styleguide_example/api/tests/test_versioning.py`. The description lists every path that moved, old beside new, and pastes the `ruff`, `mypy` and `pytest` output and the two `curl` exchanges from the sandbox.

The `Django application` workflow runs the same three commands on the pull request in both of its jobs, the Docker Compose one and the Postgres service one, so the suite has passed with the moved routes before a reviewer opens it. The agent pushes one commit for the settings and URL change, one for the renamed reverses and new test, and one for the README.

A reviewer checks that no `reverse("api:` is left anywhere, which a `grep` in the description confirms, that `request.version` really reads `v1` through the nested `v1:authentication:session` namespace, that the unversioned prefix answers `404` rather than a DRF version error, and that the README's curl examples use the new paths. Then they merge and tell API consumers the new prefix, since this change breaks the old one on purpose.

## Run it on every Linear issue labelled agent

In the console, add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled`, filtered to the `agent` label and the team whose issues describe the API. When someone labels an issue such as "clients need a stable /api/v1 prefix before the mobile release", the trigger puts the issue after the prompt and the run reads any extra constraint, such as keeping a redirect, from the issue text. Only label changes made by a person fire the trigger; changes made by an app integration never do, and the automation starts at most `max_runs_per_hour` runs in an hour.

From your own server, the same body goes to `POST /o/{org}/sessions` with the repository in `resources` and the issue's URL beside it, read through your Linear connection, plus a `request_id` that is a UUID v5 of the issue id so a retried call does not open a second pull request for the same issue.

## Why run it on Rush?

A prefix change is trivial in one file and dangerous everywhere else: a `reverse()` in a utility module, a path in the README, a test that still resolves because the namespace happens to exist. In a Rush sandbox the agent runs the real suite against a real Postgres, greps for the old namespace, and requests both prefixes from a running server, with every command and its output kept in the transcript.

The result passes the repository's own lint, type-check and test jobs before a reviewer opens it, and the new test pins `request.version` so a later settings change cannot silently drop versioning. The same request works for any DRF project whose URLs are organised by namespace.

## Frequently asked questions

### Why NamespaceVersioning rather than URLPathVersioning?

The project already names every URL through nested namespaces and reaches them with `reverse()`. `NamespaceVersioning` reads the version from the resolver namespace, so one include in `config/urls.py` versions the whole tree and the app-level `urls.py` files stay as they are. `URLPathVersioning` would add a `version` kwarg to every `reverse()` instead.

### Can the old /api/ paths keep working for a while?

Not with `NamespaceVersioning` and an allowed list, because a request that resolves under a namespace with no allowed version is answered with DRF's invalid-version error rather than served. If you need a grace period, say so in the issue and the agent adds a rewrite at your reverse proxy or a second include, and documents the trade-off.

### Does request.version work through the nested namespaces?

Yes. DRF splits the resolver namespace on `:` and takes the first segment that is in `ALLOWED_VERSIONS`, so `v1:authentication:session` yields `v1`. The new `test_versioning.py` asserts exactly that from inside a view rather than trusting the documentation.

### What changes for mypy and ruff?

Nothing in configuration. The `mypy.ini` plugins for Django and DRF type the new settings keys, and the new test module follows the import order `ruff` enforces through its `isort` rules. Both run in the workflow and in the sandbox before the pull request opens.

## More Django REST Framework jobs

- [Add an Audit Log to a Django REST Framework API from a Linear Issue](https://getrush.ai/run/add-audit-log/django-rest-framework/)
- [Add Test Coverage to CI for a Django REST Framework API](https://getrush.ai/run/add-coverage-to-ci/django-rest-framework/)
- [Add CSV Export to a Django REST Framework API](https://getrush.ai/run/add-csv-export/django-rest-framework/)

## The same job on other stacks

- [Add API Versioning to ASP.NET Core Minimal API Endpoints](https://getrush.ai/run/add-api-versioning/dotnet/)
- [Add API Versioning to a Vapor App](https://getrush.ai/run/add-api-versioning/vapor/)
- [Add API Versioning to an ASP.NET Core Web API](https://getrush.ai/run/add-api-versioning/aspnet-core/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
