Asana is moving to string IDs [Updated with revised timeline]

Community Forum English Developers & API
16

Did you try to deep dive into the library code already?

17

Yes, since I’d like to set it at global level, I believe it goes in one of the several options with the Client class (https://github.com/Asana/python-asana/blob/master/asana/client.py)? But I’m not 100% where exactly and what the option name and parameter should look like. Perhaps an example that shows how to turn the integer IDs on and off will help other forum members as well.

18

I don’t have any example, you should inspect somehow the requests that goes out and see if the header you added matches what the documentation says. @Diakoptis maybe you can help?

19

Hey @Pradyumna_Dhakal,

I don’t write in python but at the client at official library you can set headers for every request type and add your options to disable or enable things in Asana api.

def post(self, path, data, **options):
    """Parses POST request options and dispatches a request."""
    parameter_options = self._parse_parameter_options(options)
    body = {
        # values in the data body takes precendence
        'data': _merge(parameter_options, data),
        'options': self._parse_api_options(options)
    }
    headers = _merge(
        {'content-type': 'application/json'},
        options.pop('headers', {})
    )
    return self.request('post', path, data=body, headers=headers, **options

Sorry for the short response but I’m on mobile.

20

Hi @Pradyumna_Dhakal,

You can see examples of how to set headers in the client libraries in the tests for the client. You can either set them using client.headers["key"] = "value" to send them with every request, or pass headers={"key": "value"} to method calls to send them on an individual request.

For string IDs, you would set client.headers["Asana-Enable"] = "string_ids", however there is still one gap in our implementation and we are not 100% ready to begin this migration.

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?

22

If you set the headers on the client directly, they will apply to every request made with that client. If you pass them in the method call, they will apply only to that one request. Clearing the header from the client or not including them in the method call will then fall back to the default behavior, yes.

To be more explicit about the gap in our implementation: we have 100% coverage on read and write requests in the API (enabling this feature will hide numeric IDs on reads and reject numeric IDs on writes) but do not yet have support for requests that originate from within Asana (i.e., outgoing webhook payloads). If your app does not use webhooks, you can freely test the rest of the API, but we won’t be starting the clock for the deprecation until the entire API supports string IDs.

23

Got it. I’ve successfully tested switching the integer ids on an off - thanks!

24

Hi everyone! After a disappointingly large technical hurdle, we’re finally able to begin this deprecation! To recap:

  • This deprecation will operate under the name "string_ids" and can be enabled by sending an Asana-Enable: string_ids header in your requests
  • When this deprecation is enabled,
    • The API will not provide a numerical "id" field for any object in the response, and you will only receive the string "gid" field
    • The API will not accept numerical IDs in any part of the request
      • URLs and paths are already always strings and do not need to be changed
      • Form-encoded key-value pairs don’t have type information and are already always strings, so they do not need to be changed
      • JSON bodies do have type information, and you’ll need to change the fields in your request bodies from things like "projects": [123, 456] to "projects": ["123", "456"]
  • There are new settings to control the format of webhook bodies
    • The webhook objects themselves have an "always_use_string_ids" field on them which you can change to migrate individual webhooks into the new format
    • Each app in your developer console will have options for migrating the entire app as a whole (screenshots below)
    • Refer to the table in my previous post for specifics on how these two settings interact

Here’s what the app option will look like in the developer console:

04
041254×278 41.1 KB

On the matter of the timeline:

  • You can begin the deprecation starting today. The new options in the developer console will be gradually rolling out over the next week or so.
  • The “activation date” (the day on which string IDs become the default behavior) will be August 13th, 2019
  • The “end date” (the day on which string IDs become permanent) will be February 11th, 2020

As always, let us know if you have any questions about this deprecation. Because of the scope of this deprecation, we’ll be monitoring the situation closely as developers migrate their apps.

6 Likes
25
26

The new options in the developer console have now been rolled out to 100% of users.

4 Likes
27

Hello.

I am trying to send the header Asana-Enable: string_ids from the official PHP client library GitHub - Asana/php-asana: Official PHP client library for the Asana API v1.

Can you provide an example on how this is done? Thank you very much.

28

Hello all, we have an important update to share about the timeline of this deprecation.

Because this deprecation affects literally every API request and webhook, there’s a risk that we will cause a large number of heavily-used apps to encounter errors for extended periods of time if we change the default behavior in an instant on the activation date. In fact, in the last month, nearly 7,000 apps with over 230,000 users have not opted in or out of the deprecation and will almost certainly break when the deprecation is activated on August 13th.

To mitigate this, we will make changes to the default behavior in three steps:

  • August 13th, 12:00 pm PDT — we will change the default behavior from inactive to active for five minutes, turning it back to inactive at 12:05 pm. This will cause errors for large, heavily-used apps and prompt their developers to begin investigations. By only staying enabled for five minutes, we ensure that these apps are not broken for several hours or several days while their developers learn about the deprecation and try to adjust for it. (Updating code and tests to use the deprecation framework and opt-out can take significant time for large apps with complex deployments.)
  • August 20th, 12:00 pm PDT — we will change the default behavior from inactive to active for one hour, turning it back to inactive at 1:00 pm. Assuming the largest apps were caught by the previous event, this will catch the next group of apps, such as those that may not make requests more than once per five minutes.
  • August 27th, 12:00 pm 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 through sending an Asana-Disable: string_ids header to opt-out.

Please let us know if you have any questions or concerns about this timeline.

1 Like
29
30

Wow. BUT maybe it won’t be quite that dire - perhaps (hopefully) other apps are in the same boat as Flowsana: because you started passing “gid” alongside “id” many months ago, I switched to relying on “gid” for my IDs a while back. That means that I’m compatible with the new string-ID model (except for webhooks) without having to opt in or out.

“except for webhooks”
Well, OK, true, my hopeful optimism doesn’t apply to webhooks - for apps that use those and didn’t opt in or out, their webhook code will break on August 13th. (I just updated mine today, will be testing it this coming week and putting it into production next weekend.)

31

And I’ve converted Asana2Go this past weekend so your outstanding list is down to 6,999 now!

Thanks,

Larry

2 Likes
32

Hello all, I have a last-minute update about today’s scheduled “bump.” Because we are currently experiencing downtime, we will not be changing the default behavior today. We will instead be having the bump tomorrow, August 14th from 12:00 pm to 12:05 pm PDT. Sorry for the sudden change, but we are concerned that developers may attribute string-ID-related errors as fallout from the downtime and thus ignore it.

3 Likes
33
  • August 27th, 12:00 pm 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 through sending an Asana-Disable: string_ids header to opt-out.

Hi, I currently interface with the Asana API through the Ruby gem (using v0.9.2). With the recent transition of the string_ids change to active, we’ve started to get invalid request errors, which is expected.

We were upgrading from v0.6.0 and the previous error message was:

Error: #<Asana::Errors::InvalidRequest: tag: Not a valid GID type: number>

after upgrading the gem we now get

Error: #<Asana::Errors::InvalidRequest: task: Not a Long: >

I’ve looked into temporarily disabling the string id change so we can migrate on our end, by adding the Asana-Disable header:

@client = ::Asana::Client.new do |c|
  c.default_headers({ 'Asana-Disable' => 'string_ids' })
end

While the deprecation warnings have been suppressed, we’re not seeing the error going away, which might suggest the disabling isn’t coming through.

Would you be able to help me verify if Asana-Disable for this feature is working (or that’s it’s intended that it can’t be disabled anymore) and will continue until the Feb 2020 deadline? Thanks!

1 Like
34

Making a massively breaking change like this just before a long weekend is not a great plan, IMHO.

35

Said a guy who’s going to get to do a lot of manual labor since php-asana no longer seems to function, and sorting out how to make it work again is a task I’m giving up on.