# Laravel:api Surface Evolution

> Evolve APIs safely using versioned DTOs/transformers, deprecations, and compatibility tests

- Skill: `jpcaparas/laravel-api-surface-evolution` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jpcaparas/laravel-api-surface-evolution`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jpcaparas/laravel-api-surface-evolution/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: jpcaparas (https://skillmd.com/u/jpcaparas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jpcaparas/laravel-api-surface-evolution

---


# API Surface Evolution

Design for change without breaking clients.

## Versioning Strategy

- Choose explicit versioning (URI `/v1/...` or header negotiation)
- Default to additive changes; never break a released contract

## DTOs & Transformers

- Define versioned DTOs; map from models/services via transformers
- Keep controller thin—validate → transform → respond

## Deprecations

- Mark fields as deprecated in docs and responses (e.g., headers)
- Provide sunset timelines; add metrics to see remaining usage

## Testing

- Contract tests per version (request/response shapes)
- Backward compatibility tests for commonly used flows