A note about deprecating integer IDs

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 are migrating from integer IDs to string IDs due to fundamental issues in representing large integers in Javascript. For more information about this please reference our earlier post about string IDs. We have been using our deprecations framework to communicate this change but we understand that some applications may not have been prepared for such a sweeping modification of our API interface. To that end, we hope that the small change of adding this header to all requests while you convert your application to the new interface will be a fast and easy way to get up and running again!

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!