Safe API endpoint deprecation
Treat endpoint removal as a breaking change. A replacement endpoint does not authorize deleting the old one. Use the repository's API governance and a lifecycle such as:
ACTIVE -> DEPRECATED -> CUSTOMER MIGRATION WINDOW -> USAGE VERIFICATION
-> REMOVAL APPROVED -> REMOVED
When deprecating, identify the replacement and compatibility differences. Apply supported API versioning, OpenAPI/developer-portal deprecation metadata, response headers where appropriate, migration documentation, routing/feature-flag strategy, customer/consumer communication, and a realistic sunset window.
Before proposed removal:
- search routes, clients, tests, docs, generated SDKs, gateway/configuration, and internal repository references;
- identify known internal and external consumers and owners;
- inspect usage telemetry, access logs, dashboards, and monitoring over the agreed window where available;
- confirm the replacement is deployed, documented, and functionally sufficient;
- define rollback/compatibility handling and obtain the required product/API-owner approval.
No code reference is not proof that no customer calls the endpoint. Do not remove the route, DTOs, handlers, tests, or documentation without explicit user direction to perform removal. A request to add or document a replacement alone is insufficient.
During removal, preserve unrelated versions/routes, update contract tests and generated artifacts through established workflows, and verify the retired route behavior intentionally. Record approval and evidence in the repository's normal change process rather than inventing a new governance system.
1---2name: api-endpoint-deprecation3description: Plan, implement, or review deprecation and eventual removal of a customer-facing API endpoint. Use for endpoint replacement, version retirement, deprecation metadata, migration windows, usage verification, or explicit removal work.4---56# Safe API endpoint deprecation78Treat endpoint removal as a breaking change. A replacement endpoint does not authorize deleting the old one. Use the repository's API governance and a lifecycle such as:910```text11ACTIVE -> DEPRECATED -> CUSTOMER MIGRATION WINDOW -> USAGE VERIFICATION12 -> REMOVAL APPROVED -> REMOVED13```1415When deprecating, identify the replacement and compatibility differences. Apply supported API versioning, OpenAPI/developer-portal deprecation metadata, response headers where appropriate, migration documentation, routing/feature-flag strategy, customer/consumer communication, and a realistic sunset window.1617Before proposed removal:1819- search routes, clients, tests, docs, generated SDKs, gateway/configuration, and internal repository references;20- identify known internal and external consumers and owners;21- inspect usage telemetry, access logs, dashboards, and monitoring over the agreed window where available;22- confirm the replacement is deployed, documented, and functionally sufficient;23- define rollback/compatibility handling and obtain the required product/API-owner approval.2425No code reference is not proof that no customer calls the endpoint. Do not remove the route, DTOs, handlers, tests, or documentation without explicit user direction to perform removal. A request to add or document a replacement alone is insufficient.2627During removal, preserve unrelated versions/routes, update contract tests and generated artifacts through established workflows, and verify the retired route behavior intentionally. Record approval and evidence in the repository's normal change process rather than inventing a new governance system.
dprakash2101