mcpField
A
api-platform-versioning

api-platform-versioning

github.com/dev-toolingsDevelopment22775 installsUpdated 3w ago
Repository

About api-platform-versioning

A Symfony skill for choosing and implementing API Platform versioning strategies. It favors deprecation before parallel versions and covers sunset notices, response headers, documentation, and tests.

Key features

  1. 01Configure resource and operation deprecation
  2. 02Add sunset dates and response headers
  3. 03Use parallel URI versions when needed
  4. 04Document and test active versions

Use cases

  1. 01Renaming or removing API fields and operations
  2. 02Announcing an API removal timeline
  3. 03Managing breaking representation changes

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/dev-toolings/superpowers-symfony --skill api-platform-versioning

After installing, type/api-platform-versioningin Claude Code to confirm it loaded.

Bundled filesreference.md

Details

From the project README

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.

Guardrails

  • Prefer deprecation: path versioning is the fallback, not the default.
  • Always set a sunset date and keep at most 2 or 3 versions active.
  • deprecationReason and sunset are stable across v3 and v4, but the RFC 9745 headers option is v4-era: verify it on your installed version.
  • Use groups for minor additive changes rather than a new version.

Progressive disclosure

  • Use this file for execution posture and risk controls.
  • Open references when deep implementation details are needed.

Output contract

  • The deprecation or versioning strategy chosen and why.
  • Deprecated elements with their sunset dates and successor links.
  • Tests for each active version and for the headers.

References

  • reference.md

Comments

Markdown supported