William Bishop - Developing a best-in-class deprecation policy for your APIs

William Bishop

Developer Advocate at Miro

William's presentation

William's slides

Q&A

• From the three most important things when developing deprecation policy, which part is usually underestimated?
• What do nasty actions look like in real life?
• Which channels do matter the most when it comes to communicating deprecation policies? Does it belong to social media?
• When you have hundreds or thousands of API users and clients, what strategies might you use to make sure that all or most of them are aware of the deprecation or retirement?

”Trust is at the heart of deprecation”

Deprecation: The feature is no longer supported by the team. No new functionality will be released around that feature, and if there are any bugs or issues with the product, the chance that they will explore a fix is extremely low. (definition by Twitter Developer Platform)

Retirement: The feature will no longer be accessible. (definition by Twitter Developer Platform)

Why do we need to deprecate APIs in the first place?

Healthy APIs and services are constantly evolving, and the capabilities that are available of the APIs today, could be outdated or no longer necessary to the product after some time. Old versions often are:

• replaced with new versions,
• less reliable and less necessary.

Less time and resources are spent at keeping them updated. This is where deprecation comes in: we need a way to handle these older versions, and ensure the developers and users are always able to use the latest and greatest capabilities.

Deprecation is a way to offload resources that were being used for older versions, so then you can actually focus on those that continually evolve and expand your latest versions.

It’s all about developer trust

• Developer trust is the biggest risk at deprecation policies: you’re making a formal commitment that your APIs will function or stop functioning when they say they will.
• Your developers may rely on your APIs and your services as the backbone of their own services. Any disruption or misscommunication can ruin this trust.
• Developer trust directly correlates with business impact.

The biggest risk at deprecation and retirement is being ambiguous.

Ambiguity includes:

• Unclear timelines
• No internal consensus
• Undocumented behavior

How to develop a best-in-class deprecation policy?

• Have a multi-faceted initiative with input from product, engineering, customer success and other cross-functional teams.
• Be aware of the external market.
• Have someone in the team who understands developer experience.

The three most important things to consider:

• Timelines: achievable, proposed timeline for the MVP of your next API version.
• Dependencies: accounting for limitations and dependencies.
• Messaging: a clear message crafted for customers, with cross-functional buy-in.

Understanding the landscape:

• What are the industry leaders up to now?
• How does your capability fit into these standards?
• Where do you need to deviate?

Honesty and transparency above all

When developers choose to leverage your APIs, they are putting their faith in your product, and also your team’s decision making.

• If your expectations are different from what you see in reality, forcing a retirement just to meet an internal goal is not going to maintain the trust you have built with your developer ecosystem.

• When it comes to retirement, you need to be realistic and don’t shoot off a critical infrastructure of your end users and developers just to meet an internal goal.

The solution is a balance between external needs of developers and internal commitments in your organization.

The most important take-aways

• A good policy requires a cross-functional approach.
• Developers are at the heart of your decision-making.
• Invest time and resources early on.