# Add API Versioning to a Vapor App

Yes. An agent moves your Vapor routes under a versioned /api/v1 group, keeps the old paths answering with a deprecation header, tests both and opens a PR.

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

## What the agent does

The agent reads how routes are registered before it moves any, because in Vapor a version prefix belongs on the `RoutesBuilder` the controllers are mounted on, not inside each controller. In an app generated from vapor/template with Fluent, `Package.swift` takes `vapor` from 4.121.4, `fluent` from 4.13.0 and a Fluent driver, and builds the app with upcoming features such as `ExistentialAny` turned on. `Sources/App/routes.swift` registers a root route, `GET /hello`, and `try app.register(collection: TodoController())`; `Sources/App/Controllers/TodoController.swift` is a `RouteCollection` whose `boot` groups under `todos` and exposes `GET /todos`, `POST /todos` and `DELETE /todos/:todoID`, each returning `TodoDTO` values from `Sources/App/DTOs/TodoDTO.swift`. The tests in `Tests/AppTests/AppTests.swift` use `VaporTesting` and Swift Testing, hit `todos` and `hello` by path, and migrate and revert the database around each case.

The change introduces one place that owns the version. The agent adds `Sources/App/Routes/APIVersion.swift` with an enum of versions and a `versioned(_:)` helper on `RoutesBuilder` that returns `grouped("api", version.rawValue)`, then changes `routes.swift` to register `TodoController` on `app.versioned(.v1)` so the todo routes answer at `/api/v1/todos`. `TodoController` itself does not change: it still groups under `todos` relative to whatever builder it is mounted on. The `hello` and root routes stay unversioned, since they are not part of the API.

Old clients keep working during a migration window. The agent registers the same controller a second time on a `grouped("todos")`-compatible legacy builder wrapped in a small middleware that adds `Deprecation: true` and a `Link` header pointing at the `/api/v1` path to every response, so `GET /todos` still answers but says it is going away. The version also appears in a response header, `API-Version: 1`, added by the same group's middleware, so a client can tell which contract it hit. A new `DELETE` and `POST` under the legacy path share the handlers, not copies of them.

Tests are extended rather than replaced. The agent updates the three todo tests in `AppTests.swift` to call `api/v1/todos`, adds cases that `GET /todos` still returns the same list with the `Deprecation` header present and that `GET /api/v1/todos` carries `API-Version: 1` and no deprecation header, and keeps `helloWorld` as is. It runs `swift build` and `swift test` against a Postgres it starts in the sandbox with the `DATABASE_HOST`, `DATABASE_USERNAME`, `DATABASE_PASSWORD` and `DATABASE_NAME` values `configure.swift` reads, the way the template's `test-template.yml` workflow runs `swift test` inside a `swift:6.3-noble` container with a `psql` service. It also builds the `Dockerfile` with the Docker it installs first, because the template's CI does that too.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add API versioning to this Vapor app and open a pull request. Read Package.swift, Sources/App/routes.swift, Sources/App/configure.swift, Sources/App/Controllers/TodoController.swift, Sources/App/DTOs/TodoDTO.swift, Tests/AppTests/AppTests.swift and .github/workflows/test-template.yml first. Add a versioned(_:) helper on RoutesBuilder backed by an APIVersion enum, mount TodoController under /api/v1 through it without changing the controller, and keep the root and hello routes unversioned. Keep the old /todos paths answering through the same handlers behind a middleware that adds Deprecation: true and a Link header to the v1 path, and add an API-Version header on the v1 group. Update the existing todo tests to the new path and add tests that the legacy path still works with the Deprecation header and that the v1 path carries API-Version and no deprecation header. Start Postgres in the sandbox with the DATABASE_* values configure.swift reads, run swift build and swift test, install Docker and build the Dockerfile, and paste the outputs in the pull request. Do not change the Todo model, DTO or migration.",
  "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 with a new `APIVersion.swift`, a changed `routes.swift`, a small middleware file for the legacy group, and an updated `AppTests.swift`; `TodoController.swift`, `Todo.swift`, `TodoDTO.swift` and `CreateTodo.swift` are untouched. The description shows the `swift test` output listing the old and new cases, the `swift build` result, the Docker image build, and a `curl -i` of `/todos` and `/api/v1/todos` from the sandbox so the reviewer sees the headers on each.

A reviewer checks that the version lives in one enum and one helper, that the controller was mounted twice rather than copied, that the deprecation middleware is on the legacy group only, and that the `hello` route still answers at its old path. They decide how long the legacy group stays, which is one line to remove later. Then they merge; clients move to `/api/v1` at their own pace and can see the `Deprecation` header in the meantime.

## Run it on every Vapor service without a version prefix

A team with several Vapor services starts one run per repository with `POST /o/{org}/sessions`, this prompt and the repository in `resources`. The agent reads each service's own `routes.swift` and controllers, so a service that already groups under `api` gets the version added inside that group rather than a second prefix, and each run opens its own pull request.

The key's `webhook_url` receives `run.completed` for each run it starts, with a `session_url` to read the pull request link. A `request_id`, a UUID, in the body makes a retried start return the run already started.

## Why run it on Rush?

Versioning a live API is a change nobody wants to get wrong twice: the risk is not the prefix but the old clients, and whether the legacy path really behaves the same once the routes move. In a Rush sandbox the agent starts a real Postgres, runs the full Swift test suite, builds the production Docker image and sends requests to both paths, and all of that output is kept in the transcript, so the pull request shows the headers and bodies a client would receive rather than a promise about them.

It is also work to hand off from the terminal: start the run, close the laptop while Swift compiles, and come back to a pull request whose evidence is already in the description. The same request runs across every Vapor service the team owns, each in its own sandbox.

## Frequently asked questions

### Does the TodoController change?

No. It stays a `RouteCollection` grouped under `todos` relative to the builder it is mounted on. The version comes from mounting it on `app.versioned(.v1)` in `routes.swift`, so a second version later is another mount with a different controller or the same one, not an edit to the existing file.

### What happens to clients still calling /todos?

They keep getting the same responses from the same handlers, plus a `Deprecation: true` header and a `Link` header that names the `/api/v1` path. The tests cover that path explicitly, and removing it later is deleting one group in `routes.swift`.

### Why a header rather than only the path?

The path is the contract; the `API-Version` header makes it visible in logs and in a client's response inspection without parsing the URL, and it is what the deprecation middleware is compared against in the tests. Both are set in one place, the versioned group's middleware.

### How does the agent run the tests without the template's CI container?

It starts Postgres in the sandbox and exports the same `DATABASE_HOST`, `DATABASE_USERNAME`, `DATABASE_PASSWORD` and `DATABASE_NAME` values `configure.swift` reads, then runs `swift test`, which migrates and reverts around each case as `AppTests.swift` already does. The Docker build step needs Docker installed first, which the agent does with `sudo apt-get install -y docker.io` before starting `dockerd`.

## More Vapor jobs

- [Add Background Jobs to a Vapor App from a Linear Issue](https://getrush.ai/run/add-background-jobs/vapor/)
- [Add Caching to a Vapor App](https://getrush.ai/run/add-caching/vapor/)
- [Add CORS to a Vapor Server](https://getrush.ai/run/add-cors/vapor/)

## The same job on other stacks

- [Add API Versioning to an ASP.NET Core Web API](https://getrush.ai/run/add-api-versioning/aspnet-core/)
- [Add API Versioning to a Django REST Framework Project from a Linear Issue](https://getrush.ai/run/add-api-versioning/django-rest-framework/)
- [Add API Versioning to ASP.NET Core Minimal API Endpoints](https://getrush.ai/run/add-api-versioning/dotnet/)

## 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/)
