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

**URL:** <https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416>\
**Category:** Platform News\
**Created:** [21 May 2019 23:37 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416 "2019-05-21T23:37:26Z")\
**Posts on this page:** 17\
**Page:** 1

<div class="post-metadata">

**Author:** ![Matt\_Bramlage](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/matt_bramlage/32/145_2.png) [@Matt\_Bramlage](https://forum.asana.com/u/Matt_Bramlage)\
**Post date:** [21 May 2019 23:37 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/1 "2019-05-21T23:37:26Z")

</div>

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 **less than a month 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](https://app.asana.com/-/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](https://asana.com/developers/documentation/getting-started/deprecations) and learn why we are making this change in our article on [moving to string IDs](https://asana.com/developers/news/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](https://asana.com/developers/documentation/getting-started/deprecations) 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](https://forum.asana.com/t/sections-are-dead-long-live-sections).

---

<div class="post-metadata">

**Author:** ![Matt\_Bramlage](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/matt_bramlage/32/145_2.png) [@Matt\_Bramlage](https://forum.asana.com/u/Matt_Bramlage)\
**Post date:** [21 May 2019 23:40 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/2 "2019-05-21T23:40:13Z")

</div>

Pinned on 21 May 2019 23:40 UTC



---

<div class="post-metadata">

**Author:** ![Phil\_Seeman](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/phil_seeman/32/81525_2.png) [@Phil\_Seeman](https://forum.asana.com/u/Phil_Seeman)\
**Post date:** [21 May 2019 23:55 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/3 "2019-05-21T23:55:56Z")

</div>

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:

> [@Asana is moving to string IDs \[Updated with revised timeline\]](https://forum.asana.com/t/asana-is-moving-to-string-ids-updated-with-timeline/29340/21):
>
> Thanks all for your prompt responses! @Joe_Trollo, that makes it very clear. I’m assuming the settings apply only for that session and for a new session, if I don’t send in the header, the behavior will fallback to default, i.e. receiving both integer and string IDs. Also, would you advice we wait till your implementation is 100% before performing any further tests?

---

<div class="post-metadata">

**Author:** ![Bastien\_Siebman](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/bastien_siebman/32/172354_2.png) [@Bastien\_Siebman](https://forum.asana.com/u/Bastien_Siebman)\
**Post date:** [28 May 2019 08:00 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/4 "2019-05-28T08:00:58Z")

</div>

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 🤔😅

---

<div class="post-metadata">

**Author:** ![Joe\_Trollo](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/joe_trollo/32/4025_2.png) [@Joe\_Trollo](https://forum.asana.com/u/Joe_Trollo)\
**Post date:** [28 May 2019 18:25 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/5 "2019-05-28T18:25:26Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![ron\_proulx](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/ron_proulx/32/25164_2.png) [@ron\_proulx](https://forum.asana.com/u/ron_proulx)\
**Post date:** [28 May 2019 19:14 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/6 "2019-05-28T19:14:05Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Phil\_Seeman](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/phil_seeman/32/81525_2.png) [@Phil\_Seeman](https://forum.asana.com/u/Phil_Seeman)\
**Post date:** [28 May 2019 19:42 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/7 "2019-05-28T19:42:52Z")

</div>

> [@Joe\_Trollo](#):
>
> will always create a board-style project.

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.

---

<div class="post-metadata">

**Author:** ![Joe\_Trollo](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/joe_trollo/32/4025_2.png) [@Joe\_Trollo](https://forum.asana.com/u/Joe_Trollo)\
**Post date:** [28 May 2019 20:36 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/8 "2019-05-28T20:36:56Z")

</div>

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.”

---

<div class="post-metadata">

**Author:** ![Phil\_Seeman](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/phil_seeman/32/81525_2.png) [@Phil\_Seeman](https://forum.asana.com/u/Phil_Seeman)\
**Post date:** [28 May 2019 20:50 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/9 "2019-05-28T20:50:03Z")

</div>

> [@Joe\_Trollo](#):
>
> we’re considering exposing that option

That would be fantastic, Joe!

> [@Joe\_Trollo](#):
>
> For migrated workspaces, although the data model will be boards-style, the default view should still be “list.”

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

---

<div class="post-metadata">

**Author:** ![Joe\_Trollo](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/joe_trollo/32/4025_2.png) [@Joe\_Trollo](https://forum.asana.com/u/Joe_Trollo)\
**Post date:** [28 May 2019 22:59 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/10 "2019-05-28T22:59:52Z")

</div>

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).

---

<div class="post-metadata">

**Author:** ![Darlene\_Steele](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/darlene_steele/32/16100_2.png) [@Darlene\_Steele](https://forum.asana.com/u/Darlene_Steele)\
**Post date:** [31 May 2019 19:41 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/11 "2019-05-31T19:41:22Z")

</div>

We use [https://forms.asana.plus/](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?

---

<div class="post-metadata">

**Author:** ![Joe\_Trollo](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/joe_trollo/32/4025_2.png) [@Joe\_Trollo](https://forum.asana.com/u/Joe_Trollo)\
**Post date:** [31 May 2019 20:23 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/12 "2019-05-31T20:23:59Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Jon7](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/jon7/32/27224_2.png) [@Jon7](https://forum.asana.com/u/Jon7)\
**Post date:** [10 July 2019 17:40 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/13 "2019-07-10T17:40:52Z")

</div>

@Joe_Trollo

Hi Joe, thanks for the heads up regarding the API changes. I’ve enabled client.headers[“Asana-Enable”] = “string\_ids” in my python application so gids can be used instead of id going forward.

My concern is regarding change #2 Sections data model is changing. I am not clear if this change will affect my application. Currently the only thing my application does is a nightly export of all tasks in my list projects. I am not using sections in my application, but my users do use it via the Asana Web UI. I am currently searching for tasks by the project and storing all the metadata in a list and then iterating through each task in the list. Below is a snippet of my code.  
"  
tasks = client.tasks.find\_by\_project(project[‘gid’], {“opt\_expand”:“name,   
projects, workspace, gid, due\_on, created\_at, modified\_at, completed,   
completed\_at, assignee, assignee\_status, parent, tags, custom\_fields”})  
"

Will change #2 affect my application in any way?

---

<div class="post-metadata">

**Author:** ![Joe\_Trollo](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/joe_trollo/32/4025_2.png) [@Joe\_Trollo](https://forum.asana.com/u/Joe_Trollo)\
**Post date:** [10 July 2019 20:06 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/14 "2019-07-10T20:06:08Z")

</div>

Hi @Jon7, yes, you will be affected by the sections migration. Currently, listing all tasks in a list-view project will include old-style task-sections. After the migration, these tasks-sections will be converted to column-sections and will no longer appear when you fetch all tasks in the project. Also, there will be no more “list projects” once the migration is finished. All projects will be able to be viewed as both a board and a list.

---

<div class="post-metadata">

**Author:** ![Jon7](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/jon7/32/27224_2.png) [@Jon7](https://forum.asana.com/u/Jon7)\
**Post date:** [10 July 2019 20:39 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/15 "2019-07-10T20:39:08Z")

</div>

Thanks Joe,

Just to be clear, are you saying that my application built via the python API will be affected or how I interact with Asana via the UI? My application exports all tasks (“real tasks”, not “section tasks”) out of my project and does not discriminate based on “task-sections”.

From the " [Sections are dead! Long live sections!]" post you mentioned there are 3 paths I can take regarding this change, and one of them is do nothing because my application actually does not use section to determine task information. Based on what I am reading I don’t think I need to change my code but I wanted some clarity for my use case, which is outlined above.

Thank you so much for the quick response!

---

<div class="post-metadata">

**Author:** ![Phil\_Seeman](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/phil_seeman/32/81525_2.png) [@Phil\_Seeman](https://forum.asana.com/u/Phil_Seeman)\
**Post date:** [10 July 2019 20:56 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/16 "2019-07-10T20:56:25Z")

</div>

What @Joe_Trollo is saying is that currently, when you retrieve all tasks from a list-view project, your list of tasks includes any sections which exist in the project - because in the current data model, in list-view projects, sections are merely tasks with a flag on them to indicate that they’re sections. You might not doing anything special with those section-tasks; you might not even realize they’re in there, but they are.

After the migration, when you retrieve all tasks from a project, any sections which exist in the project will no longer be included in the list of objects you get - because they will no longer be tasks (but rather will be their own distinct object type). So in that sense, the migration will change what’s included in what you’re retrieving.

The other thing he points out which will be different is that there will no longer be any distinction of “list-view” vs. “board-view” projects. Every project will be identical in terms of its data model, and will be able to be viewed in either format in the UI. So when you say “a nightly export of all tasks in my list projects”, realize that there won’t be any concept of a “list project”, there will just be “projects”. That might or might not affect which projects you’re exporting, but probably something you want to think about.

---

<div class="post-metadata">

**Author:** ![Matt\_Bramlage](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/matt_bramlage/32/145_2.png) [@Matt\_Bramlage](https://forum.asana.com/u/Matt_Bramlage)\
**Post date:** [10 February 2020 22:56 UTC](https://forum.asana.com/t/reminder-about-two-big-upcoming-api-changes-string-ids-and-new-sections/50416/17 "2020-02-10T22:56:40Z")

</div>

Pinned on 10 February 2020 22:56 UTC


