API endpoint deprecation sequence
Phased API deprecation with backward compatibility and client migration.
API endpoints live longer than their creators expect. When you need to retire an old endpoint, a simple cutover breaks clients in production. This template shows the safe way: a grace period with deprecation headers (Sunset, Deprecation) where the endpoint still works but warns clients to migrate, followed by a hard cutoff with a 410 Gone response that forces the switch.
The sequence includes logging so you can track which clients are still calling the old endpoint and who hasn't migrated yet. This data drives your sunset date decision: you cut over once the last critical client has moved to the new endpoint.
When to use this template
- API versioning strategy — document your deprecation timeline to internal stakeholders and external partners before you announce it.
- Client migration planning — use this to coordinate with customer engineering: which customers are on the old endpoint? When can they realistically migrate?
- Incident postmortems — if a deprecated endpoint caused an outage, this diagram clarifies what the rollout plan was and where execution diverged.
How to adapt it
Extend the sequence to match your rollout strategy:
- Add a beta phase — insert an early branch where clients explicitly opt into the new endpoint before you deprecate the old one.
- Include circuit breaker logic — if v1 calls spike unexpectedly, have the server downgrade the deprecation to a warning instead of cutting over.
- Model multi-step deprecation — if you have v1, v2, v3, chain the sequences: v1→v2 (6 months), then v2→v3 (6 months later).
Visual edits regenerate clean code for documentation and team alignment on timelines.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
participant Client
participant API_Server
participant Logging
Client->>API_Server: Call v1/endpoint (deprecated)
API_Server->>API_Server: Check sunset date
alt Before sunset date
API_Server->>Logging: Log deprecation warning
API_Server->>Client: 200 OK + Deprecation header
Client->>Client: Log warning to console
else After sunset date
API_Server->>Client: 410 Gone
Client->>Client: Fallback to v2/endpoint
end
Client->>API_Server: Call v2/endpoint (new)
API_Server->>Client: 200 OK + data
Frequently asked questions
- What is an API deprecation sequence diagram?
- It visualizes how an API gradually retires an old endpoint while giving clients time to migrate: the old endpoint returns 200 with a deprecation header, then after a grace period returns 410 Gone, forcing clients to switch to the new endpoint. It shows the communication and the branching based on time.
- Why include the deprecation warning in the sequence?
- The warning phase is critical for adoption. If you cut over immediately from 200 to 410, clients break in production. A 6-12 month grace period with clear headers (Sunset, Deprecation) and logging gives client teams time to migrate without panic. The sequence makes this two-phase approach visible.
- How do I customize this for my API's versioning scheme?
- Replace 'v1' and 'v2' with your actual version names. Adjust the response codes and headers to match your spec (Deprecation, Sunset, Link headers are common). If you support multiple clients, add conditional branches for high-value vs low-value clients. Visual edits regenerate clean code.
- Should I include metrics collection in this diagram?
- Yes. Add a Logging participant and log calls to both v1 and v2 so you can track adoption. When you see the last v1 call from your biggest customer, that's when you can safely remove the old endpoint. The diagram becomes a map for your rollout strategy.
Related templates
API versioning strategy
Managing breaking changes while maintaining backward compatibility.
Contract testing sequence
Consumer and provider verifying API contracts in isolation.
Multi-provider API integration with fallbacks
Try primary provider, fallback to secondary, log failures for audit.