Deprecating API Endpoints
Last Updated: April 30, 2025
In Vets API, legacy endpoints are often left behind after migrations or feature changes, with little visibility into their usage or ownership. Over time, this has resulted in orphaned code, unclear routing paths, and growing confusion among teams, particularly as documentation becomes outdated and feature toggles no longer reflect actual behavior and orphaned code is left in place. Because cleanup and deprecation efforts aren’t always prioritized, technical debt builds and slows future development. Establishing clear, actionable deprecation guidance will help teams confidently phase out unused endpoints, reduce risk, and maintain a healthier, more maintainable API ecosystem. The following subsection details the guidance for deprecating endpoints in Vets API.
Deprecation Guidance
To maintain a reliable and maintainable developer ecosystem in Vets API, it's essential to adopt consistent patterns when deprecating endpoints. Without a clear deprecation lifecycle, legacy endpoints can remain indefinitely, which often times lead to orphaned code, outdated documentation, and confusion across teams. The following guidance outlines best practices and operational steps for deprecating API endpoints effectively, with a focus on Rails-based API deprecation strategies.
Below, the checklist is designed to guide you through the key steps of deprecating an API endpoint in Vets API.
📘 Need more detail?
Refer to the full Endpoint Deprecation Guide for timelines, communication strategies, and implementation examples.
Deprecation Checklist
📣 Communication & Coordination
Announce the deprecation to relevant teams via Slack, documentation, and cross-team meetings
Confirm product owners, stakeholders, and downstream consumers are informed
Update internal documentation around your product/endpoints
Document a deprecation plan and timeline and socialize with relevant parties
📈 Tracking & Metrics
Set up a Datadog dashboard to track traffic and deprecation progress (ex: Traffic volume levels)
Optionally, add logging or custom Datadog tags to monitor usage
APM monitoring dashboards can also be useful
Add alerts for unexpected spikes or fallback traffic
Monitor remaining traffic through Datadog dashboards or logs
Use metrics and logs to identify which consumers are still calling the deprecated endpoint
If traffic persists close to the deprecation deadline, reach out directly to the teams still relying on the endpoint. Include guidance for migration or next steps and reinforce the removal timeline
🔁 Routing & Rollout
Introduce a feature toggle to switch between old and new implementations
Note: If the endpoint is being deprecated with no replacement, use a feature toggle to gradually disable access or return a standardized deprecation message. This can help teams phase out usage gracefully and monitor any unexpected traffic before full removal
Support dual routing or parallel service calls during the transition period
Gradually roll out the new implementation using the feature flag (ex: % rollout, user based rollout)
Note: First, test the rollout in lower environments
🛠 Code & API Hygiene (Vets API)
Clearly mark deprecated endpoints in the controller with comments and optional response warnings
Isolate legacy endpoints behind a version namespace (ex:
v0::Deprecated)Update Vets API Swagger documentation to indicate deprecation and planned removal
Deprecate any related classes, serializers, service objects, vcr cassettes or test data
Remove stale mock data tied specifically to the deprecated path
Note: Some mock and test data is shared, so if another team is using these integrations, please leave them in place
📌 Ownership & Cleanup
Ensure Vets API CODEOWNERS is up to date and includes the deprecation work and updates for removed files
Create a follow-up ticket for full removal after the deprecation window closes
Validate that the deprecation/removal is reflected in onboarding docs and integration guides
Help and feedback
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.