Note: this page describes our deprecation process. You may also want to reference the changelog documentation as well as see the changelog section of the forum where we list all of the active changes.
In general, a breaking change refers to a change in an API that may require you to update your application or integration in order to avoid disruption. These changes may include:
Expanding the space of types or values that clients must handle
- Adding a new value to a built-in enum field
- Allowing a reference to be
null, where it could not before
Changing the structure or meaning behind existing information
- Migrating a property to have a new type (such as
- Migrating a property to have a new type (such as
Adding new restrictions to perform an existing operation in the system
- Only allowing a method to be called if some new condition is met, where this was not true before
Removing the types or values that clients can provide
- No longer allowing a value to be null where it could before
- Newly enforcing that a numeric value is nonzero
- Removing a property
Removing a capability of the system
- Removing a mutation or some of its behavior
Whenever possible, the Asana API aims to preserve backwards compatibility for its users. Apps you write on top of the API now should, in ideal situations, continue to work indefinitely. However, there are a few rare cases where breaking changes are required. For example:
- When we identify a stability threat, we may need to partially limit or entirely deprecate the culprit feature in the API.
- When making a change in a backwards compatible way results in a cluttered, brittle, and confusing interface to Asana.
- When not making a breaking change poses a security vulnerability, such as when we migrated from SSLv3 to TLS 1.0.
If a breaking change is required, the API team will provide a number of resources to help our developers get through the change:
- We will communicate early, and through a variety of channels. We recommend that you join the developer community and configure notifications for the changelog section of the forum.
- We will provide a clear description of the change, how it affects your requests, and a migration plan to follow to transition through the deprecation.
- We will designate a deprecation period during which you will be able to choose between both old and new behavior from the API, allowing you to test out the change without having to put your entire app at risk.
While the previously-mentioned communication channels are the best place to learn about upcoming changes, the API itself will also alert you of upcoming changes. Shortly after we post communication, the API will begin sending
Asana-Change headers in the responses. These headers will have two or three pieces of information:
- The unique name of the change
- A URL to our blog post describing the change
- Optionally, a flag indicating that your specific request would be affected.
This header may be present multiple times in the response if there are multiple ongoing changes. Here's an example of one of these headers:
Asana-Change: name=security_headers;info=https://asa.na/api-sh;affected=true Asana-Change: name=other_change;info=https://asa.na/api-oc
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.
During the deprecation period, you can test out how the API will behave by sending additional headers in your requests. Sending an
Asana-Enable header including comma-separated names of features will turn those features on for that request. Sending an
Asana-Disable header will do the opposite and turn those features off for that request.
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.
The start, activation, and end dates will clearly be documented in our communications. These days may be pushed into the future if we discover that developers need more time to migrate their apps, but they are guaranteed to never occur sooner than documented.
These dates are arranged such that, if a developer happens to miss our communication and their app breaks when the default behavior changes on the activation date, they can begin sending the
Asana-Disable header to restore the old behavior and use the remaining half of the deprecation period to make their app compatible.
Here is an example of how these headers would look:
Asana-Enable: security_headers,another_change Asana-Disable: a_third_change
Aside from reserving the right to push the date of changes to a future date, the precise time during the activation date is not specified. However, since the default will only affect your integration if you do not pass either the
Asana-Disable headers for a particular deprecation, you can ensure predictable behavior of our API for your app during the entire period, including throughout the activation date.
The way we recommend you implement these changes in your integration is this:
- Whenever you detect a new
Asana-Changeheader, log these requests and be sure to take note that a change is coming. Recall that the
infokey in the header will contain a link with the details.
- Identify the nature of the upcoming deprecation and decide if your integration is sensitive to the change, paying particular attention to the cases where we return
- If changes are necessary in your integration, test the new behavior manually by making requests with
Asana-Enableset to the name of the deprecation. This should provide a clear example of the new behavior as it is implemented in our API.
- Implement the changes in your integration in such a way that it can handle the new behavior and be sure to pass the
Asana-Enableheader when you make requests. This will ensure that you will always get the new behavior regardless of when the default behavior changes.
At this point, your integration has been migrated to the new behavior. At any point after the end date the
Asana-Enable header will be ignored by the Asana API and you can feel free to remove it. We strongly recommend keeping it all the way through the end date in case of unforseen circumstances that cause us to temporarily reset the default behavior from the new implementation to the deprecated behavior.
Updated about 19 hours ago