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

api-platform-resources skill

safe

This skill helps you design and enforce explicit API Platform contracts in Symfony, mapping operations, validation, and security for robust REST resources.

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

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-resources
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 resources tasks.
---

# Api Platform Resources (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, actionable API Platform resource contracts for Symfony projects. It helps define explicit operations, DTOs, mapping, validation, and security so your API behavior matches documentation and expectations. Use it to reduce ambiguity, prevent accidental data leaks, and keep contract drift under control.

How this skill works

The skill inspects resource definitions and operation-level contracts, then produces changes to resources, DTOs, providers, and processors with explicit mapping rules. It also applies operation-specific validation and security constraints and produces a short rationale for decisions. Finally, it includes functional verification notes for happy and negative paths to confirm behavior.

When to use it

Designing or evolving API Platform resource contracts and operation boundaries
Aligning serialization groups, validation, and security per operation
When preventing implicit exposure of internal entity fields
Before a public API release or version bump to avoid contract drift
When adding DTOs or custom providers/processors to reshape payloads

Best practices

Keep contract definitions explicit and version-aware; treat operations as first-class artifacts
Map DTOs to entities with explicit field mappings rather than relying on default serialization
Apply operation-level validation and security rules, not just global rules
Document rationale for contract and security decisions alongside code changes
Include functional checks for both happy paths and negative/edge cases

Example use cases

Convert an internal entity to a public-facing DTO with explicit read/write operations
Add a custom POST processor that validates and authorizes a complex payload before persistence
Lock down a sensitive field so it is excluded from serialization in certain operations
Version an endpoint by introducing a new resource contract while keeping legacy behavior intact
Verify that OpenAPI docs and serialization groups accurately reflect runtime behavior

FAQ

Will this change runtime behavior or only documentation?

It targets runtime behavior by producing concrete resource/DTO/provider/processor changes and accompanying verification notes; documentation updates should follow to keep APIs in sync.

How does it prevent accidental exposure of internal fields?

By enforcing explicit mapping and serialization groups per operation and recommending DTO use, it avoids implicit entity field exposure.