# API versioning and deprecation policy

Flower Computer Company's public content API is currently served under `/api/v1`. The API is unauthenticated and read-only.

## Versioning

- Breaking changes use a new major version in the URL, such as `/api/v2`.
- Compatible additions may be made within `/api/v1`, including new optional fields, endpoints, and documented response types.
- Existing fields do not change meaning within a major version.

## Deprecation

The current `/api/v1` API is active and is not deprecated.

Before a supported API version or resource is retired, Flower will provide at least 90 days of notice. Affected responses will include:

- A `Deprecation` header using the structured date format from RFC 9745.
- A `Link` header with `rel="deprecation"` pointing to this policy or a migration guide.
- A `Sunset` header using the HTTP-date format from RFC 8594 when a shutdown date has been scheduled.

The `Sunset` date will not precede the `Deprecation` date. Migration guidance and a replacement URL, when available, will be published before retirement.

## Discovery

- OpenAPI description: https://www.flowercomputer.com/api/openapi.json
- API status: https://www.flowercomputer.com/api/v1/status.json
- Contact: https://www.flowercomputer.com/contact/index.md