Hello all, I have a rather unfortunate update.
Sometime between when we did all the engineering and testing work for string IDs about 10 months ago and when we activated the string ID change this past month, we introduced a bug in our configuration. This impact of this bug is that only some routes and features of our API are excluding numeric IDs by default. In particular: webhooks, event streams, and PUT
/POST
routes now exclude numeric IDs from their responses. Meanwhile, the rest of our API is still returning the id
field by default if you haven’t opted out of the deprecation.
This means that we still have half of this deprecation we need to activate, and it actually accounts for a lot more than half of the API and its traffic. If you are not using the deprecation headers, your app is operating in a half-old, half-new world and there is still a very large possibility that it will break with the next activation. Once again, to mitigate the impact, we will “bump” the API for a short period of time to help apps discover incompatibilities without breaking them for too long. The schedule for the remaining rollout is as follows:
- September 17th, 10:00 am PDT — we will change the default behavior from inactive to active for two hours, turning it back to inactive at 12:00 pm. We will be monitoring the impact from this “bump” through a number of channels. Depending on the magnitude of the impact, we may postpone the final activation.
- September 24th, 10:00 am PDT — we will change the default behavior from inactive to active and keep it active. From this point on, old behavior will only be accessible by sending an
Asana-Disable: string_ids
header to temporarily opt-out.
To summarize, you will fall into one of these three categories and should take the recommended action:
- If you have already opted in or out by passing in deprecation headers, you have no further action to take.
- If you have changed your code to leverage string GIDs but are not sending headers, please check that you have applied the changes to your code using our read endpoints as these have still been providing numeric IDs.
- If you haven’t yet taken action on this deprecation, your app may already be malfunctioning, so please modify your app to use string GIDs or delay the deprecation by opting out by sending an
Asana-Disable: string_ids
header.
Some background about the bug and its discovery
Background: The API has a “live” configuration that, when changed, will immediately be reflected in the active API deployments. In this configuration, we list out all the ongoing deprecations and whether they are enabled by default. This is actually a list, too, and not a mapping. These are the settings we change on the start, activation, and end dates for deprecations. There is also a “base” configuration that is used as a fallback for things not specified in the live configuration. The final configuration is determined by taking the base configuration and “merging” it with the live configuration, overwriting appropriate keys.
Additionally, those of you who have been around for a while may recall that we rebuilt our API to improve performance. Due to internal technical limitations, we unfortunately have to maintain both the new and old systems. The old handles webhooks, event streams, and writes of data, while the new handles reading data.
Bug: The old system (which was correctly activated) read default values for our deprecations, and then completely replaced the list of settings with the live configuration. The new system read the default values, and then extended that list with the live configuration. This led to a final configuration that was akin to deprecations: ["something else", "string IDs are off by default", "another thing", "string IDs are on by default"]
. (We don’t actually use a list of strings like this—we’re not monsters!) When we later used this list to determine what the default behavior should be, we took the first matching setting in the list, which indicated that string IDs should not be activated.
Discovery: I was making some manual API requests to debug a script I was creating, and was not bothering to pass any deprecation headers. I then noticed in the responses that the id
field was still being included, which kicked off the investigation.
Remediation: We will be changing our configuration parsing to assert that no deprecation appears twice in the final list of settings.
Thank you for your patience as we try to roll out this especially difficult deprecation! Please let us know if you have more questions or concerns.