api-platform-serialization_skill

Overview

This skill delivers clear, version-aware API Platform contracts for Symfony with explicit operations, mapping, and safety controls. It focuses on serialization boundaries, DTO/resource mapping, and policy-safe behavior so APIs behave predictably across releases. Use it to reduce drift between documentation and runtime serialization.

How this skill works

The skill inspects operation-level contracts and enforces explicit payload boundaries by recommending or producing resources, DTOs, providers, and processors. It applies operation-specific validation and security constraints and documents the mapping and rationale for each change. The workflow includes functional verification across happy and negative paths and produces artifacts and verification results as output.

When to use it

• Designing or evolving API Platform operations and contracts
• Aligning serialization with validation and security requirements
• When migrating entities to explicit DTOs or resource models
• Before releasing breaking changes that affect payloads or permissions
• To audit and prevent divergence between docs and runtime behavior

Best practices

• Define operation-level contracts first; avoid relying on implicit entity exposure
• Use DTOs to isolate API shapes from internal models
• Apply validation groups and operation-level security expressions consistently
• Document mapping decisions and rationale with each change
• Run both positive and negative functional tests to confirm serialization and access control behavior

Example use cases

• Add a create operation that accepts a DTO and maps to an entity via a processor, with strict validation and role checks
• Introduce a partial update (PATCH) that only exposes allowed writable fields and uses a custom provider to hydrate the entity
• Audit an existing API to remove implicit entity field exposure and replace with explicit serialization groups
• Version an endpoint by introducing a new resource class and mapping to preserve older contracts while evolving behavior
• Verify that documentation, OpenAPI output, and runtime serialization remain in sync after refactors