0011-laravel-api-surface-evolution

To evolve a Laravel API without breaking existing clients, introduce explicit versioned contracts and additive-by-default updates. Use versioned DTOs and transformers to map domain models so controllers stay thin while maintaining backward compatibility.

The best way to deprecate fields in a Laravel API response is to mark them deprecated in both the response and documentation with clear sunset timelines. This provides visibility into ongoing usage and allows clients time to adapt to the changes.

Versioned DTOs and transformers map domain models to version-specific data transfer objects, keeping controllers thin. This approach isolates response shape changes per API version, allowing safe evolution and controlled change management across different client expectations.

Yes, you need contract testing for Laravel API backward compatibility. Maintaining per-version contract tests and running backward-compatibility tests for common flows ensures stable endpoints used by existing client apps remain functional during API evolution.

You should use additive updates in Laravel API versioning by default when evolving request and response shapes. This strategy biases changes toward adding new fields rather than modifying or removing existing ones, reducing the risk of uncontrolled regressions.

Yes, you can use header-based versioning for Laravel API deprecation and sunset planning. The approach supports explicit versioning strategies, allowing you to document deprecation timelines and manage controlled changes across different API versions safely.