Api Platform Versioning (Symfony)

Use when

• A field, operation, or resource is being renamed or removed and consumers need time to migrate.
• Announcing a removal date to clients with Sunset and Deprecation headers.
• Deciding between deprecation and parallel /v1 and /v2 surfaces.
• A breaking representation change that deprecation and groups cannot express.

Default workflow

1. Try deprecation first: set deprecationReason on the resource, the operation, or #[ApiProperty].
2. Add sunset: with a date, and on v4 add headers carrying Deprecation (RFC 9745) and a Link with rel="successor-version".
3. Before v4, emit those headers from a KernelEvents::RESPONSE listener.
4. Only if still breaking, expose parallel uriTemplate values (/v1, /v2) with distinct groups, or output DTOs with one provider per version.
5. Mark the old operation as deprecated in OpenAPI, document the changes per version, and test every active version.