Fixing breaks: the fast way, and the correct way
As with any software product we continuously iterate on our API. Whenever possible we do this in a way that doesn’t create a breaking change in our API interface, but sometimes we have to make a modification that we know will affect our apps. We built our deprecations framework to make it as easy as we can to empower our developers to fix breaks quickly when changes happen.
We are currently in the middle of one such change as we replace integer IDs with string IDs. We are deprecating the number-based
id field in favor of a string-based
gid field. The fastest way to fix your application is to send a HTTP header on all requests:
Asana-Disable: string_ids which will disable the behavior that only provides strings. Note that this temporary solution will only be valid until 2020-02-11. The full fix is to replace all usage of
id in favor of
gid for all interactions with our API (including webhooks, which can be configured for this in our developer console ).
We encourage you to take this opportunity to not only make the modifications for your integration to restore its functionality but also to familiarize yourself with the features of our deprecation framework, because this is how Asana is going to evolve our API over time. When we have an upcoming deprecation in the works we will send an
Asana-Change header which is intended to be used by your integration to alert a maintainer however you wish (logging, email, warning page) whenever there is an API interface change for you to handle. Please consider building in alerts that take advantage of this header to keep you up to date with what we’re creating in Asana’s API as we continue to iterate on it!
In addition, we’ll keep our page on deprecations up to date with all our API changes and timelines for them.
Thank you for your understanding and support! If you have any questions, concerns, or need assistance please head over to the Asana Forum’s Developers and API category to spark a discussion!