# London Night Guide API Versioning & Deprecation Policy

> The stability contract for the London Night Guide Content API (https://londonnightguide.com/openapi.json). Canonical URL: https://londonnightguide.com/developers/deprecation/

## Versioning

- JSON endpoints are **URL-path versioned**: the current version is `/api/v1/`.
- A breaking change ships as a new prefix (`/api/v2/`); it never mutates an existing version in place.
- Within a version, changes are additive only: new endpoints and new response fields may appear, existing fields are never removed or retyped.
- Unversioned content URLs (`/{slug}/`, `.md` paths, `/llms.txt`, `/sitemap.xml`, `/feed/`) are stable and follow the same additive-only rule.

## Deprecation Timeline

1. **Announcement** — the deprecated operation is marked `deprecated: true` in https://londonnightguide.com/openapi.json and noted on this page.
2. **In-band signalling** — every response from a deprecated endpoint carries a `Deprecation` header and a `Sunset` header (RFC 8594) with the retirement date.
3. **Overlap** — the old version keeps working for **at least 90 days** after the Sunset header first appears.
4. **Retirement** — after the sunset date the endpoint returns 404 with the standard JSON error envelope pointing at its replacement.

## What Agents Should Do

- Treat a `Deprecation` or `Sunset` header on any response as the migration signal; the replacement endpoint is named on this page and in the spec.
- Re-fetch https://londonnightguide.com/openapi.json periodically — the `info.version` field increments on every contract change.

## Currently Deprecated

Nothing. Every documented endpoint, including all of `/api/v1/`, is active with no planned sunset.

## Contact

Questions about API stability: concierge@londonnightguide.com