# La Maison du Mile-End API — versioning and deprecation policy

> What the version in the URL promises, what would break it, and how much warning you get. Applies to every endpoint under `https://www.maisonmileend.ca/api/v1`.

## Versioning scheme

The major version is carried in the **URL path**: `/api/v1`. The current version is **v1**, and every response repeats it in an `API-Version` header.

Path versioning rather than a header, because a path survives being copied into a curl line, a browser bar, a log line or a bug report — and a version you cannot see in the URL is a version nobody notices they are pinned to.

## What can change inside a major version

These ship without notice. A client that ignores fields it does not recognise will not break:

- new endpoints
- new optional request parameters
- new fields on an existing response object
- new error codes on an existing status

## What forces a new major version

These never ship inside an existing version:

- removing or renaming a response field
- changing the type or meaning of a response field
- making an optional request parameter required
- removing an endpoint
- changing an HTTP status for an existing outcome

## How a retirement is announced

A retired version keeps answering for at least **180 days** after it is marked deprecated. During that window every response from it carries:

| Header | Spec | Meaning |
| --- | --- | --- |
| `Deprecation` | RFC 9745 | the date this version became deprecated |
| `Sunset` | RFC 8594 | the date it stops answering |
| `Link` | RFC 8288 | rel="successor-version" pointing at the replacement |

`Deprecation` and `Sunset` are HTTP dates (IMF-fixdate), per their specifications — not ISO 8601. The `Link` header names the replacement, so a client can follow it without a human reading a changelog.

## What is deprecated right now

Nothing. `v1` is current and carries no deprecation headers.

## Where else this is stated

- `https://www.maisonmileend.ca/agents.md` — the same policy inside the full agent instructions
- `https://www.maisonmileend.ca/openapi.json` — restated in the spec description
- `https://www.maisonmileend.ca/api` — the machine-readable index, under `versioning`