Asana-Change, Asana-Enable, Asana-Disable headers

English Forum Developers & API
1

hey folks, do you use any of the following headers?

Request

  • Asana-Enable
  • Asana-Disable

Response:

  • Asana-Change

Do you ever use the affected=true portion of the Asana-Change header?

I’m looking at improving these headers and enhancing their usability and I want to understand how familiar people are with them and how they use them.

Many thanks,
Sasha (on behalf of the DevRel team)

2

I’ve used only Asana-Enable and Asana-Disable for the basic purpose intended and found them helpful and worked as expected.

Thanks,

Larry

3

Same here.

1 Like
4

I have used the flags to disable or enable a feature, but also to get rid of this annoying log alert “this call may be affected by bla bla bla”… I have no idea what affected does.

5
6

Thank you for opening this conversation @sasha_f and checking with the community! :bowing_woman: Here’s my usage and thoughts about each header…

Asana-Enable

I’ve only used Asana-Enable via the PHP SDK and absolutely love it! Usually APIs add entirely new endpoint paths like /api/v2/... but I really enjoy this simple opt-in approach with the headers. The header makes it super simple to test the deprecation and then enable the upgrade whenever our code is confirmed compatible.

Asana-Disable

I personally haven’t had a need yet to use Asana-Disable since it often isn’t useful for a long period of time. I typically confirm code compatibility before Asana-Disable is needed, per the docs:

If no header is specified, the default behavior will be determined by how far into the deprecation period we are:

  • Before the start of the deprecation period (the “start date”) the feature will be disabled, and it will not be possible to enable it.
  • After the start date, the feature will be disabled by default, but you can begin choosing whether to enable or disable it.
  • In roughly the middle of the deprecation period (the “activation date”) the default behavior will switch and the feature will be enabled by default. You can continue to disable it with the appropriate header.
  • At the end of the deprecation period (the “end date”) the feature will be enabled and you will no longer be able to manually disable it.

Asana-Change

I also find the debug log nags from the PHP SDK incredibly helpful and informative. This is how deprecations are ever brought to my attention. I suspect these nags are generated by the PHP SDK from the Asana-Change header’s information.

Questions/Concerns/Uncertainties

When exactly is the Asana-Change header deployed? Is this notification sent before the deprecation period’s start date (per the above outline) or after the start date? That’d be dumb if I was notified and then added the new feature to my Asana-Enable header before the change was even available for opt-in. :upside_down_face: I usually am not too strict of the deprecation schedule because I just confirm the opt-in as soon as I can prioritize it.

What about opt-ins that are no longer needed? From my current understanding, it seems I will forever be stacking on Asana-Enable values. How do we confirm when a feature no longer needs to be enabled and is enabled by default? It’d be nice to clean up the code for self-documentation purposes. Should I just try removing the older values from the header to see if I still get an Asana-Change nag? Is that the protocol?

I wish there was better clarity around deprecation/change dates. I know dates can sometimes get moved around, so digging through a long forum thread doesn’t feel reliable. This leads me to not feel too confident about the main forum posts since it could be outdated. Perhaps the official release schedule could be posted in the Asana-Change headers, as well? A concrete, source-of-truth would be nice. Perhaps a changelog in the API Reference while the forum post still remains for general discussion, testing feedback, announcement, etc. would actually be ideal. Or maybe even a Google Calendar we could add to our own calendars and receive automatic notifications of dates and their changes. I’m just shouting out ideas here… :slightly_smiling_face:

4 Likes
7

This is phenomenal feedback, thank you!

Addressing a few things:

this is great to know. We’re working on new client libraries (let me know if you want to be part of the alpha / beta), and will make sure to include this on the list of stuff.

This varies a lot. I try to encourage teams to make the Asana-Change header available as soon as possible, but that doesn’t always happen. Usually, it is added at the same time as my announcement in the forum, or shortly after (links to the forum posts are included in the headers).

Another point of confusion that even I recently learned: the header conveys the list of active changes. If you make an API call that is or will be directly affected by the change, the change includes the affected=true entry! I always interpreted that as indicating that the change was actively affecting the API call, and not that it is or will be affecting the API call. I’m working on improving this and including a enabled=true state for when the change has actually been turned on!

Once the Asana-Change header disappears, the change is no longer active, and the Asana-Enable or Asana-Disable headers are ignored. There is one other state where the Asana-Change can appear, but the request headers are ignored: that is when the feature is fully deprecated but we have not removed the header yet. This is also something I want to improve and make unambiguous in how we present the Asana-* headers.

Honestly, me too. I don’t think that the dates will get simpler just yet (although I’m beginning to try selling the idea of monthly API changes rather than ad hoc, but that convo is very early). I do think that exposing whether the change has been enabled for this request or not via a new enabled=true entry will help mitigate that. Here’s how I expect this to work:

  • when devs want to support a change, they can pre-emptively check the change headers for the enabled=true value and use that in conditional statements to determine how their app behaves.
  • enabled=true would start appearing the moment that the feature is enabled
  • and so devs wouldn’t need to worry about the exact date as long as they added support (the conditional check for enabled=true) before the exact launch date

What do you think?

8

Thank you for the thorough response and insights @sasha_f!

So let me see if I understand the proposed enabled=true correctly…

  • Asana-Change is generally present to indicate a breaking/affecting change is planned
  • Asana-Change: ...enabled=false would mean this is simply a warning notification and the change is not yet able to be enabled or disabled by Asana-Enable or Asana-Disable
  • Asana-Change: ...enabled=true would mean there is a change available that we can now actually enable or disable
    • The language here may be a little confusing… enabled=true even while we have Asana-Disable? Is the language rather more accurately available=true? Or is the header to confirm the change is enabled by default and/or that our Asana-Enable header is actually having an affect?

I’m also wondering how the PHP SDK (and other client libraries) would work with this information. I don’t directly use or even look at the response headers since it’s all abstracted away when using a client library, so that sounds like a concern to me. The current development experience is that I call methods in the PHP SDK to get the data I need—and sometimes logs happen. This is to say, I’m not really sure how I would go about this suggestion:

I totally agree that the exposed data should reflect what’s actually happening in Asana’s implementation. As we mentioned, dates are hypothetical and decoupled from actual code implementation, so I really like the idea of having a simple flag like enabled=true as a final source of truth! I’d hope the SDKs can change the log language depending on the full details of the Asana-Change header, as it seems to already subtly do per the docs:

Note: If your request is not affected, we will not claim affected=false. This is in case, during the deprecation, we detect that the change has a larger scope than initially thought. A request going from “you may be affected” to “you definitely are affected” is an acceptable update, but a request going from “you definitely are not affected” to “you definitely are affected” is not an acceptable update.

For example, “An upcoming change is planned” versus “A change is available”.

Even with the flag, though, dates are still useful to know so we can plan our developments accordingly, of course. :slight_smile:

9

No, this would mean “this change is actively modifying the response of this API request”

We would never issue an enabled=false just like how we never issue an affected=false (those states are communicated by their omission).

The reason this is confusing is because we can actually have the following state:

Request: Asana-Disable: some_new_feature
Response: Asana-Change: some_new_feature;affected=true;enabled=true

What the above means is that when a request is handled by the server, the server may choose to ignore the change header (disable, in this example) and instead issue a request that has the new change enabled. This actually occurs already for requests when they have reached their “deprecation date” and are no longer available for opt-out. The only difference between my proposal and what we do now is the presents of enabled=true.

Fantastic point. We may need to switch to an entirely different header (maybe Asana-Change2, or Asana-Changes, or Asana-Version) if we start providing a new key that the old client libraries are not capable of parsing (enabled=true).

We need to share a state diagram that identifies the possible transitions and states for changes

And yeah! We would def keep dates around. This would only work if devs had enough prep time and accurate docs that enable them to support a feature.