api-platform-versioning_skill

Overview

This skill helps deliver robust API Platform contracts in Symfony by making operations, mappings, and policy behavior explicit and version-aware. It guides teams through defining operation-level boundaries, implementing resource and DTO changes with clear mapping, and validating security and serialization to prevent contract drift. Use it to keep API behavior predictable and safe across versions.

How this skill works

The skill inspects API Platform operations and enforces explicit contract definitions for each operation, including input/output DTOs, providers, and processors. It checks mapping rules, serialization groups, validation constraints, and operation-level security to ensure implementation matches the declared contract. It produces an output contract summarizing changed artifacts, security decisions, and functional verification results.

When to use it

• When designing or evolving API Platform endpoints and you need clear operation-level contracts.
• When introducing a new API version and you must avoid breaking clients or leaking internal fields.
• When aligning serialization, validation, and security behavior across multiple resources.
• When reviewing changes to providers, processors, or DTO mappings to prevent contract drift.

Best practices

• Define operation-specific DTOs rather than reusing entities directly to avoid implicit field exposure.
• Declare explicit serialization groups and validation constraints per operation to keep docs and runtime aligned.
• Apply operation-level security rules instead of relying solely on global voters to limit scope errors.
• Document contract changes and rationale with each versioned change to aid reviewers and testers.

Example use cases

• Introduce a v2 POST operation with a different payload shape while keeping v1 stable for existing clients.
• Refactor an entity to a DTO-backed write model and implement processors that map inputs deterministically.
• Add stricter validation to a public operation and verify negative paths do not leak internal state.
• Audit an API to detect operations that implicitly expose entity fields and replace them with explicit DTOs.