Proposed Web APIs Deprecation Scheme

I have been looking around for an API deprecation scheme that makes it easier for the API providers as well as consumers to understand and implement. I have to say there are many schemes on the internet if you did a simple search, what I present below is a simple scheme that should be fairly easier to implement as well as easier to adapt to from consumer perspective. Have a look and let me know your comments.

Before you start, the proposed scheme assumes the following API runtime lifecycle.

Now, with the scheme that maps to each step in the previous lifecycle diagram.

If the image resolution is very low, you can download the full excel sheet from here.

In order to implement this scheme, your API needs to have a configurable HTTP response code at runtime, that is the API should not have the response code, for example, the HTTP 200 OK, hard coded. Otherwise, it will be very difficult to change in case a new version of the API comes up.

The listed status codes in this table are the ones to be returned in case of a successful API response, In the case of failed response, normal error codes would be returned, for example, 400 Bad Request.

It is very important that your API documentation lists these scenarios clearly with sample request and response. Also, your consumer needs to be aware that a resource MAY be modified to return a "redirection" response code (e.g. 301, 302) instead of directly returning the resource. Clients should handle HTTP-level redirects, and respect HTTP headers (e.g. Location) to avoid service disruption. Please note that using HTTP redirect assumes a certain level of API compatibility between the deprecated version and the new version.

Finally, this scheme assumes a 90 days grace period is enough for the consumers to migrate to the new API version, you may want to change it to 180 days or any other value that best suits your consumers.