Deprecating an older API

Best practices for using deprecation headers for endpoints, parameters etc. in older API version

Actions to undertake before stopping older API functionalities

Migration Announcement Email

Send Migration Announcement email to developer customers, emphasizing the final date when the older APIs will stop working. We recommend sending the email atmost 6 months prior to the day older APIs will function for the last time. The following information should be highlighted in the email:

• Last date and time of Older API versions functioning: YYYY-MM-DD hh:mm (timezone)

• List of APIs versions affected - URLs

• Reasons for their deprecation

• List of environments and services affected - URLs

• Latest API versions, already up and running, that would replace the older ones and their documentation - URLs

• Benefits of newest versions

• List of possible blackout tests, along with their dates and times.

We recommend sending subsequent reminder emails every two months with the 6-month migration period. A Sample Email template can be found here.

Official announcements in Social Media

Make an official announcement about the migration process on the company website or developer portal. This could be company news, with the contents from the migration email curated to accommodate this. Announcements should also be made from the company page or handler in related social media sites like Twitter, LinkedIn, StackOverflow, etc. Specifically, StackOverflow engagement can work better to answers developer queries and assure them about their worries.

Retweeting or reposting can also be done to remind customers about the deprecation deadline.

Changes in Documentation

Notify developers of the upcoming Older API deprecation by including a small announcement text in the relevant API documentation. The announcement should include the last date of API(s) functioning and links to endpoints of the latest versions, documentation, and (if possible) new SDKs.

A tagline, named deprecated or sunset, depending on the approach you undertake for stopping an older version API to function, should be appended in the API documentation. More about this is discussed in upcoming sections.

Provide communications means in the documentation so that developers can contact and ask questions or share their worries.

At the time close to the deadline, we recommend removing documentation for the older APIs so that they are no longer accessible to new customers as well as the existing ones.

Sunset of Deprecation information in API Response headers

Designs need to be changed and implemented for the API responses for the older versions.

Depending on the strategy taken, include sunset or deprecation header(s) in API responses, mentioning date and times when the API(s) will no longer work or be given maintenance support, endpoint URLs and documentation links to the newer API versions, etc.

Changes in SDKs

Using analytics to monitor API endpoint usages

If older API version endpoints are already being monitored by some usage analytics, inspect the changes in usage traffic after the migration announcements and executing blackout tests. See if the usage traffic is still high in these endpoints or no.

If the traffic continues to be high or to increase, we recommend approaching the users still working with the older versions and asking them about the reasons they are still using them. They should be made aware of the possible consequences when the older APIs will no longer work. In addition, they should be assisted to migrate to the newest versions with the required assistance.

Executing API Blackout Tests

We recommend executing atleast 3 API blackout tests, where customers will be unable to request older API versions in any environments (e.g. Sandbox, Production, etc.).

Emails announcing and reminding about blackout tests should be sent to customers prior to the date when the test will be executed. The email should include the date, time (inc. timezone), estimated duration of the blackout test, affected APIs and services, and alternate APIs to use during this period. A sample email template can be found here.

Arrange blackout tsts on such day(s) of a week, so that it affects the customers in the least possible ways. If possible, we recommend executing blackout tests on weekends (e.g. Saturday or Sunday)

Sunset header or Deprecation header?

Before earlier versions of APIs stop working for good, any response sent back from these APIs should contain either a Sunset Header or a