home / skills / makfly / superpowers-symfony / api-platform-versioning

api-platform-versioning skill

safe

This skill helps you design and evolve API Platform contracts in Symfony with explicit versioned operations, mappings, and policy-safe behavior.

npx playbooks add skill makfly/superpowers-symfony --skill api-platform-versioning

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.2 KB

---

name: symfony:api-platform-versioning
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Deliver robust API Platform contracts in Symfony with explicit operations, mapping, and policy-safe behavior. Use for api platform versioning tasks.
---

# Api Platform Versioning (Symfony)

## Use when
- Designing or evolving API Platform contracts and operations.
- Aligning serialization, validation, and security behavior.

## Default workflow
1. Define operation-level contract and payload boundaries.
2. Implement resource/DTO/provider/processor changes with explicit mapping.
2. Apply operation-specific validation and security constraints.
2. Validate functional behavior across happy and negative paths.

## Guardrails
- Keep API contract explicit and version-aware.
- Avoid exposing internal entity fields implicitly.
- Prevent drift between docs and actual serialization.

## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.

## Output contract
- API artifacts changed (resource/DTO/provider/processor).
- Contract/security decisions and rationale.
- Functional verification results.

## References
- `reference.md`
- `docs/complexity-tiers.md`

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.

FAQ

What output should I expect after running this skill?

A concise contract summary listing changed artifacts (resources/DTOs/providers/processors), documented security and policy decisions, and functional verification results for key paths.

How does this prevent documentation drift?

By enforcing explicit serialization groups and DTO boundaries per operation and requiring contract updates alongside implementation changes, so docs reflect actual runtime behavior.