API Deprecation

API deprecation marks an API version or endpoint as planned for eventual removal, giving consumers time to migrate. A deprecated API can remain functional during a transition period, but clients should move to its replacement.

Deprecation is a lifecycle signal, not necessarily an immediate shutdown. A server can continue serving a deprecated endpoint while documenting its replacement and communicating a removal timeline.

For a Java backend, deprecation can apply to an HTTP endpoint, request or response field, API version, or Java method used to implement the API. The important distinction is between telling clients that an interface should no longer be used and actually removing it.

A useful migration process is to announce the deprecated interface, document the replacement, provide enough overlap for clients to migrate, monitor remaining usage, and eventually remove the old interface. The exact transition period depends on the API's compatibility requirements and release policy.

Deprecation is especially important for versioned APIs. For example, `/api/v1/orders` might be deprecated after `/api/v2/orders` becomes available. Existing consumers can continue using v1 temporarily, while new development should target v2.

In Java code, the `@Deprecated` annotation can mark a Java declaration as deprecated and enable compiler or IDE warnings. That annotation does not by itself remove an HTTP endpoint or force external clients to upgrade; API lifecycle behavior must be handled through the service's contract and deployment process.

Key points

• Deprecation signals that an API should no longer be used and may be removed later.
• A deprecated endpoint can remain available during a migration period.
• Deprecation should include a documented replacement and migration guidance.
• Usage monitoring helps determine whether clients have migrated before removal.
• Java's `@Deprecated` annotation concerns Java declarations; it does not automatically retire an HTTP endpoint.

Interview questions

What is the difference between deprecating and removing an API endpoint?

Deprecation tells clients that an endpoint should no longer be used while it may continue operating. Removal makes the endpoint unavailable and can break clients that still depend on it. A controlled migration period reduces that compatibility risk.

What is API deprecation?

API deprecation means an API interface is still available but should no longer be used for new development. The provider normally identifies a replacement and gives consumers time to migrate. Later, the deprecated interface may be removed according to the published lifecycle policy.

How would you safely deprecate an API version used by external clients?

I would first publish the replacement contract and migration instructions, then announce the deprecation and its planned lifecycle dates. I would measure traffic to the old version and identify important consumers where possible. After usage falls sufficiently and the migration window has elapsed, I would remove the old version in accordance with the API's compatibility policy.

Does Java's `@Deprecated` annotation deprecate an HTTP endpoint?

No, not by itself. `@Deprecated` marks a Java declaration so tools such as the compiler or IDE can warn developers who use it. An HTTP endpoint is part of an external API contract, so its deprecation must also be communicated and enforced through the web service's documentation, lifecycle policy, and deployment behavior.

What information should a deprecation notice contain?

A useful notice identifies the affected API, explains what consumers should use instead, and provides migration guidance. It should also communicate the relevant lifecycle dates or conditions, along with compatibility considerations. For externally consumed APIs, the notice should be easy for clients to discover through documentation and appropriate operational communication.