---
name: api-change-safety-net
description: Catch regressions when changing an existing API endpoint. Write a failing test that pins the current behaviour before making any change, so a broken contract shows up as a red test instead of a production incident. Use whenever editing, renaming, deprecating or extending an existing route, handler, or response shape.
---

# API Change Safety Net

## When to use

- Editing an existing endpoint's logic, validation, or error paths
- Renaming or removing response fields
- Adding query params, middleware, or auth to a live route
- Deprecating a route that still has callers

Do NOT use for greenfield endpoints - there is no old behaviour to pin.

## The rule

Before touching the implementation, prove the current behaviour with a
failing test. The order is fixed:

1. **Pin.** Write a test that asserts the endpoint's CURRENT behaviour:
   status code, response shape, headers that callers rely on, and the
   error bodies. Run it. It must pass against the unmodified code.
2. **Change the expectation, not the code.** Edit the test so it asserts
   the NEW intended behaviour. Run it. It must now FAIL. If it passes,
   your test was not pinning anything - fix the test first.
3. **Implement.** Make the smallest change that turns the new test green.
4. **Sweep.** Grep for other callers of the changed shape (frontend
   selectors, other services, docs snippets) and list them in the PR
   description, even when you did not update them all.

## What to pin, in priority order

1. Response field names and types actually read by callers
2. Status codes for the failure modes callers branch on
3. Header names - HTTP headers are case-insensitive on the wire but NOT
   in every client library; pin the exact casing the client reads
   (v0.3.1 exists because this was missed)
4. Ordering guarantees of list responses
5. Pagination defaults and cursor format

## Hard boundaries

- Do not write the fix before the failing test exists and has been seen red.
- Do not run the project's full suite; run only the pinning test file.
- Do not refactor neighbouring code while you are in the file.
- When deprecating a route: update the docs IN THE SAME CHANGE as the
  deprecation marker. A deprecated route with stale docs is the
  regression this pack is known for - check it explicitly.

## Reporting back

End with a short block: what was pinned, what was seen red, what turned
green, and the caller sweep results. If any caller could not be checked,
name it - do not imply coverage you did not verify.
