Reminder about two big upcoming API changes (String IDs and new sections)

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.

5 Likes

Hi @Matt_Bramlage!

I also found that in terms of the string-IDs change, this thread has some really useful info from you guys, especially as it relates to upcoming webhook changes:

3 Likes

Thanks for the details. What about projects that are created with the API? Does the format you need to use depends on the migration status of the organization? Sorry if my question does not make sense :thinking::sweat_smile:

As workspaces and organizations are migrated, new projects created in those workspaces will automatically use the new data model, i.e., we will ignore the layout field in the request to create a project and will always create a board-style project.

as for most requested features, I hope one of them is the ability to “collapse history” in a note/todo. seeing endless “xx changed the due date…” lines makes for a very messy card.

I understand I think you’re saying “board-style” in terms of the data model, but how will we convey what the initial UI view should be for a new project? It’ll be really important for integrations like Flowsana that it creates new projects displayed initially in a List view.

We don’t support setting the “view” of a project through the API, but now that we have four different views (list, board, calendar, and timeline) we’re considering exposing that option. We’ll post more about that when we have new information.

For migrated workspaces, although the data model will be boards-style, the default view should still be “list.”

That would be fantastic, Joe!

Excellent! How about new projects created via the API? Also still “list”? :crossed_fingers:

Yep, sorry, I wasn’t clear there—I was specifically referring to API behavior. In the web app, the project creation flow is changing to accommodate the new data model and there may not be a default (i.e., users might have to choose the default view when creating the project).

1 Like

We use https://forms.asana.plus/ to have our Wufoo forms automatically load into Asana. Will this be effected by this change and do we need to do anything?

Hi @Darlene_Steele, integrations and apps built or maintained by Asana will be updated by our internal teams to support the coming API changes.