# Version an endpoint and keep the old one working

A breaking change released behind a new version, with the old one kept working until every user has moved.

Category: API surface and contracts
Source: https://letsship.ai/use-cases/version-a-route-and-ship-the-shim
Published: 2026-08-25

## Goal

Version one route and provide a compatibility shim for the previous shape.

## Acceptance criteria

- Both versions are covered by tests
- The old version keeps working unchanged
- A deprecation date is recorded and communicated
- Usage of the old version is measurable so the removal can be evidence-based

## What lands as proof

Both versions under test plus usage measurement, which is what makes the eventual removal safe.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Version {route} and add the compatibility shim

Description: Version one route and provide a compatibility shim for the previous shape.

Acceptance criteria:
- Both versions are covered by tests
- The old version keeps working unchanged
- A deprecation date is recorded and communicated
- Usage of the old version is measurable so the removal can be evidence-based

Before you create the issue, name the breaking change this repository needs and replace {route} with the endpoint. Say who the known consumers are.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: version one route and provide a compatibility shim for the previous shape. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means old and new both covered, the deprecation date recorded, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops for the plan, and the review bar is raised afterwards so that smaller suggestions block the merge too, not only serious findings.