Skip to content
Prompt Words
History

API versioning

Also called: versioned API, v1 and v2 endpoints, API version header.

Giving each shape of an API a version, in the URL like /v2/ or in a header, so old apps keep working when the API changes. Breaking changes go into a new version, and the old one keeps running until an announced end date.

v2 renamed price to amount. Each app calls its own version, so both keep working. Here the version is in the URL; a header like Api-Version works the same way.

/v1 calls: 0 · /v2 calls: 0 · Times a screen broke: 0

No calls yet. v2 renamed the field price to amount; v1 still sends price.

    No calls

    Say it in a prompt

    Version the public API in the URL. Move today's routes under /v1, build the changed orders response under /v2, keep /v1 running for 12 months, and add a Sunset header with the shutdown date to every /v1 response.

    Vague vs precise prompt

    Vague prompt

    rename the price field to amount in the API

    Typical resultRenames the field everywhere at once. Every mobile app still on an older release breaks the moment the change is deployed.

    Precise prompt

    Add API version 2026-09-01, chosen with an Api-Version header and defaulting to each client's pinned version. Only in that version rename price to amount; older versions keep price. Note it in the changelog and announce an end date for the old version.

    Typical resultOld apps keep getting price, new clients opt in to amount, and nothing breaks on deploy day.

    Seen on

    • Stripe API: Versions are dated, like 2026-08-26.dahlia; each account has a default version, and the Stripe-Version header overrides it for one request.
    • GitHub REST API: The X-GitHub-Api-Version header picks a dated version; requests without it get 2022-11-28.

    You might describe it as

    • change the API without breaking the old app
    • keep v1 working while we build v2
    • old mobile apps still call the old endpoints