API Deprecation: Definition, Best Practices, Examples

What is API deprecation?

API deprecation is the formal process of phasing out an API endpoint, version, parameter, or response field. The deprecated thing still works during a sunset period, but consumers are warned to migrate. Eventually, the deprecated piece is removed (called "sunset"), and clients still calling it break.

Deprecation is how mature APIs evolve without breaking existing integrations overnight. It's the contract between API provider and consumers: "We're changing this. Here's the timeline. Here's the alternative."

Deprecation lifecycle

Sunset windows range from 6 months (small APIs) to 3+ years (Stripe, Twilio).

HTTP standards for deprecation

HTTP/1.1 200 OK
Deprecation: Sat, 1 Jun 2026 00:00:00 GMT
Sunset: Sat, 1 Dec 2026 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"
Content-Type: application/json

What gets deprecated

• Entire API versions (e.g., v1 → v2)
• Specific endpoints (e.g., POST /users replaced by POST /v2/accounts)
• Request parameters (e.g., ?email= replaced by ?identifier=)
• Response fields (e.g., created replaced by created_at)
• Authentication methods (e.g., API keys → OAuth 2.0)
• Webhook event types
• SDK methods

Deprecation best practices

• Announce early. 6+ months for non-trivial changes; 12-24 months for major version cuts.
• Document the migration path. Old → new field mapping with code examples.
• Use Sunset / Deprecation headers. Machine-readable warnings.
• Email known consumers. If you have user accounts, contact them directly.
• Track usage. Know who's still calling deprecated endpoints; reach out.
• Provide a transition period with both APIs running. Don't force a flag day.
• Versioning strategy. URL path (/v1/ vs /v2/), header (API-Version), or query param.
• Document the changelog. What changed, why, when. Searchable + linkable.
• Brownouts before sunset. Disable old API for short windows (e.g., 1 hour) to flush remaining clients.

Common deprecation pitfalls

• Silent breakage. Removed without notice. Customers furious.
• No migration path documented. "Use the new API" without mapping = nightmare.
• Sunset window too short. Customers on yearly release cycles can't move in 90 days.
• Removing field that's still in use. Track call patterns before removal.
• Forgetting SDKs. SDKs depend on API; coordinate SDK release with deprecation.
• No replacement. Deprecating without offering equivalent functionality.
• Communication only via blog. Customers don't read blogs. Use API headers + email + in-product banners.

Example: GitHub API deprecation

GitHub announces breaking changes ~12 months ahead, marks them in REST API + GraphQL schema, emails active OAuth app maintainers, and includes Sunset + Deprecation headers. The 2020 v3-to-GraphQL push gave customers 24+ months.

Example: Stripe API versioning

Stripe pins each API key to a specific version date (e.g., 2024-04-10). New versions are opt-in; old versions are supported essentially forever. This avoids forced migrations entirely — at the cost of carrying many concurrent versions in code.

FAQ: API deprecation

How long should a sunset window be?

6+ months for small changes; 12+ months for major version cuts. Larger enterprise APIs often offer 2-3 years.

Should I version my API?

Yes for any API with external consumers. URL versioning (/v1/) is simplest. Header versioning is more elegant but harder to test.

What's the difference between deprecation and sunset?

Deprecation: announced, still works. Sunset: actually removed. Deprecation precedes sunset by 6-24 months.

How do I know who's calling my deprecated API?

Log per-endpoint usage with consumer ID (API key, OAuth client ID, user ID). Email top users; in-product banners for self-serve customers.

What HTTP status code for sunset endpoints?

410 Gone is the canonical answer. Some APIs use 404, but 410 communicates "was here, now intentionally gone."

Should I deprecate or just keep adding new fields forever?

Add new fields freely (additive changes are non-breaking). Deprecate when removing OR changing semantics.

What if customers don't migrate?

Brownouts (short outages) before final sunset. Final sunset blocks remaining clients — communicate well; offer support.

Test API version coexistence with LoadFocus

During deprecation windows, LoadFocus runs JMeter and k6 scripts against both old and new API versions to verify behavior consistency under load. Sign up free at loadfocus.com/signup.