Integer to String ID conversion

Asana currently uses numerical IDs for all references, but we are running out of them. Once we surpass 253, JavaScript loses precision and is no longer able to accurately represent every ID. You can observe this by opening up a JavaScript console and seeing that 2**53 + 1 == 2**53 evaluates to true. Because of this, we must move away from numerical IDs before we reach that point, and by consequence that means our developers also need to move away from numerical IDs.

The API team is actively working on this migration both within our internal code and in the public API’s interface. Because of the scope and complexity of this change internally, you will start to see some of these changes leak (in backwards compatible ways) before we’re ready for you to move to string IDs yourself. However, we want to share the plan with you to provide clarity and minimize confusion during this change.

The preparation

Starting now, you will start to see objects containing two ID fields: the current, numerical id field and a new, string gid field. Additionally, places where the API accepts IDs as inputs will begin to accept both numbers and strings depending on which key you send to us. Here’s an example of the new schema for objects in our API. Notice how the id field is an integer in the JSON payload and gid is a string in double quotes:

"data" : {
  "id" : 153678405088703,
  "gid" : "153678405088703",
  "name" : "An Asana task"

If you store Asana IDs in a service outside Asana (such as an SQL table), please start planning how you will migrate IDs in these services to become strings. For example, if you are using an SQL table, you will want to change from a type like BIGINT to a type like VARCHAR.

The change

Once we have comprehensively confirmed that the API is fully able to support string IDs, we will be using our deprecations framework for the migration. You’ll be able to send a flag in your request headers that enables the new behavior. This consists of two aspects:

  1. When enabled, objects will not contain an id field. They will contain only the gid field as their ID.
  2. When enabled, the API will reject API requests that use numbers instead of strings to reference objects.

After we have opened this up with the deprecations framework, the old behavior will be the default for about six months. Then, the new behavior will become the default and there will be another six months during which you can select the old behavior. After that, the API will operate with the new behavior fully and the old behavior will not be available. (Please refer to our deprecations documentation for more information about this process.)

The future

After the migration is complete, IDs will only ever be strings. Additionally, that is the only guarantee that Asana can make about IDs. We make no guarantee that IDs will simply be the string representation of integers—newly issued IDs may have letters in them as well. Therefore, you must transition your format to handle strings.

Please let us know if you have any questions about string IDs, and we’ll answer them in this thread. We will be sending out more communication over the coming months as we get closer to completion of the work on our end and the finalization of a timeline.


What does gid mean?

This stands for “global ID.” In Asana, IDs are globally unique, across all workspaces and even across all data types. gid feels like a logical alternative to id and also conveys more information about Asana’s schema.

My code was already using strings. Why not just make id a string instead of removing it?

While we will do our best to make sure that all developers hear about this change in some form, the truth is that some will still fall through the cracks. There are also several libraries and frameworks out there that will silently coerce strings to numbers where asked, and if we left in the id field these applications might never notice the change.

If we remove this field, we force every developer to react during this migration period, during which they still have a chance to choose between old and new behavior and can quickly recover if their app breaks. If we don’t remove this field, it’s possible for a developer not to notice the change during the migration period. Then, after the migration period is over and the new behavior is cemented, we could send an ID with letters in it that would break their app and there would be no safe recovery.

What about existing IDs?

Any ID that was already issued by Asana will continue to be the only ID associated with that object and will not change with this migration. If you have an ID, the only transformation you need to apply is turning it into a string for storage (and using this string for the gid field moving forward).

How long will these new IDs be?

Asana’s new string IDs will not exceed 31 characters in length. If you are using an SQL table, this means that you can use VARCHAR(31) as the column type for IDs. This will allow the storage of IDs in at most 32 bytes (with an extra byte allocated by your database to encode the length of each ID).