Hello, Asana developers! We are a short time away from some major changes in Asana’s API that will have a big impact on every Asana integration and we want to call your attention to them again.
Numerical IDs are being deprecated
We are approximately 3 months away from requiring string IDs by default for resources in Asana, yet the vast majority of integrations are not selecting a behavior for handling resource ID.
If you are unsure whether your integration is fully prepared to support string IDs everywhere and to use the
gid field exclusively, your integration will break. Note, in particular, this includes the resource ID we return from our webhooks which need to be configured inside of Asana in our developer console.
However, it’s possible to prepare now! You can read more about how to have a smooth transition in our documentation for deprecations and learn why we are making this change in our article on moving to string IDs.
The current default API behavior allows the use of either string IDs or numeric IDs, but on August 13 we will change the default behavior to require string IDs in our API, so let’s get ready by then!
Sections data model is changing
Asana is moving to a new data model for sections that enables users to view all projects as both a list and a board. This has been our most-requested improvement for a long time so we’re excited to roll it out, but the nature of this change is that it might be a fairly complex process for our integrations.
The future state is that all projects will behave in our API just as board-layout projects do today. For example, working with sections in board-view projects in our API requires using the
/sections endpoint, and board-layout sections are not returned when getting tasks in the project.
Both of these behaviors will become the new reality for list-view projects by the end of this transition. If your integration assumes that sections can be fetched from the
/tasks endpoint or looks for tasks with names that end it a colon it will break during and after this transition. In addition, for the duration of the transition integrations must be prepared to handle data representing both the old and new state.
This complexity arises from the migration process itself. Asana will migrate existing old-style sections to new-style sections on a gradual basis, one domain at a time, between late May and throughout the fall. Integrations can’t manage or control the timing of this migration. Integrations must be ready for handling a project that is in one of and/or actively changing through these states:
The project is not migrated and has old-style sections if it’s a list layout.
The project is being migrated and is read-only; its sections will be actively changing during this time. Most projects will be in this state for a few minutes, but some very large projects might take longer.
The project has been migrated and has new-style sections and always behaves like a board-layout project.
The best way to prepare is through these two actions:
Ensure your integration works well with board-layout projects.
Ensure your integration can handle an in-transition project appropriately.
We’re using our deprecations framework to make list-view projects behave more like board-view projects, but this migration is unusual in that integrations can’t control or toggle the state of the project at any point in time. A feature of our deprecations framework is allowing an integration to quickly and temporarily revert our API to the deprecated behavior if it breaks, but this is not possible for this migration.
We’ve added some temporary features to our API for integrations to be ready and empowered to handle the transition, but integrations must be built to use them if they are to handle the transition well. Read our API team’s forum post for further details.