All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading