Migrate the API: $ARGUMENTS
Step 1 — Identify Breaking Changes
Read the current API and identify what needs to change:
- •Renamed or removed endpoints
- •Changed request/response schemas
- •Changed authentication flow
- •Changed error response format
- •Changed URL paths or parameter names
Categorize each change:
- •Breaking: Clients will fail without code changes
- •Additive: New fields/endpoints — existing clients unaffected
- •Deprecation: Old behavior still works but is discouraged
Step 2 — Design the New Version
Create the new API version structure in a new version directory under the API layer.
Rules:
- •Previous version endpoints MUST continue working unchanged
- •New version endpoints live in a new router with updated version prefix
- •Shared logic stays in the service layer — NOT duplicated per version
- •New Pydantic models can extend or replace previous models
Step 3 — Implement New Version
- •Create new version directory with router files
- •Add new Pydantic models to the models file (suffix with version if different)
- •Register the new version router in the app factory
- •Previous version router remains registered and functional
Step 4 — Deprecation Headers
Add deprecation headers to previous version endpoints:
python
response.headers["Deprecation"] = "true" response.headers["Sunset"] = "<date>" response.headers["Link"] = '<new-version-url>; rel="successor-version"'
Step 5 — Tests
- •Previous version tests MUST still pass unchanged (backwards compatibility)
- •Write new tests for new version endpoints in a new test file
- •Test that previous version responses include deprecation headers
Step 6 — Documentation
- •Update project documentation with both version endpoint tables
- •Update OpenAPI description noting deprecation
- •Add migration guide for consumers
Step 7 — Verify
Run the test command and the type-check command (see project config). ALL tests pass — both versions.