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

api-platform-serialization skill

safe

This skill helps you define explicit API Platform contracts in Symfony for serialization, validation, and security across operations.

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

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

Files (2)

SKILL.md

1.3 KB

---

name: symfony:api-platform-serialization
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 serialization tasks.
---

# Api Platform Serialization (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 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

FAQ

What outputs should I expect from this skill?

A list of changed API artifacts (resources, DTOs, providers, processors), the contract and security decisions with rationale, and functional verification results for key flows.

How does this prevent exposing internal fields?

By recommending explicit DTOs/resources and serialization groups, and by enforcing mapping and processors that only include intended fields and apply access checks.