Hello again, I’m back with the second announcement of the week! There are unfortunately situations where the API needs to introduce backwards-incompatible and potentially breaking changes. For example, upgrading to TLS or dropping support for API keys. Looking forward, we see several instances where we’ll need to introduce changes like this, and decided to build a system that lets us handle them in a uniform way rather than on a case-by-case basis. We’ve published both our process around how we will roll out these changes as well as how our developers can use this system to safely migrate your apps in our deprecations documentation.
We’re first using this framework to add new security headers to our API responses. Because these headers may break some non-compliant browser clients, we’re going to give developers the opportunity to check how their apps react and make changes if necessary. You can read more about the new headers in our blog post.
Let us know if you have questions about the new security headers or the deprecations framework in general. In the very near future we’ll be using this framework to launch a major API feature 
so keep an eye out for that!
3 Likes
Hey Joe. I have been amazed about the process you follow to manipulate the changes and I would like to know if is yours team invention or a common practice.
Thanx a lot
This is a process that we developed internally. Back when we deprecated API keys we created an “amnesty” header so that, if a developer was caught off-guard by the deprecation, they could send this special header and be exempted from the deprecation for a while, giving them time to replace their API keys with personal access tokens. This new framework is a generalization of that system that can be applied to arbitrary deprecations.
The more common practice is to have stronger API versioning, where we would release a new version whenever we had a breaking change and developers would choose which version they wanted. We considered this alternative and may have a versioned API in the future, but it is a much larger investment that we do not currently have the resources for. A versioned API would also face the same issues of communicating about breaking changes, providing migration windows, and allowing developers to recover when caught off-guard.
3 Likes
Thanx a lot. I learned so much from Asana about culture and I keep learning about dev ops also :))
3 Likes
Hey Joe,
One thought: how about keeping a page in the Asana Developers Documentation listing in one place all of the currently-active (and upcoming) changes utilizing the deprecations framework? It could be tough keeping up with what’s currently active and in what stage each change is at in its lifecycle if folks have to rely on looking trough the blog posts and forum threads. Would be cool to have one central list for reference.
3 Likes
@Phil_Seeman, that’s an excellent idea, and so we’ve updated our documentation to include a table of all active and upcoming deprecations.
2 Likes
Awesome, thanks - it’s perfect!