There have been a number of exciting and long-asked-for updates in Asana’s API since our last newsletter. Here are some features that we’ve recently shipped—and upcoming changes to keep an eye on.
Developers have long been asking for more powerful server-side querying to find data in Asana. While some basic filtering has been available for a long time, we often hear that client-side filtering is still necessary for more advanced use cases. This can slow apps down and make their implementation more complicated. It also means apps are receiving more data than they actually care about.
To solve these issues we’ve released our search API. This feature exposes much of the functionality in Asana’s Advanced Search to integrations, meaning that developers can now combine a variety of filters to select exactly the data their apps need. Now apps can request only tasks with a particular custom field or a combination of assignee and due date (as two common examples) and get the data back fast enough to feel interactive to users.
This feature represents a major improvement in how precisely apps are able to request data. Be sure to read the docs to see if it fits your use case!
Reacting to changes in our API
At Asana we try hard to maintain our published interface that your integrations rely on, but sometimes this is not possible. In particular, as new features are added to our web product and our API, the interface can be affected in a non-backwards-compatible way.
As Asana is rapidly creating and evolving features, we want to make this reality as painless as possible while not blocking improvements to the product. This is why we built our releases and deprecations framework: to enable apps to programmatically detect and surface upcoming changes with plenty of time to react and without requiring a developer to keep a constant eye on this blog. Once a developer is aware of the change, our framework enables them to switch to the new behavior on their own timeline. Developers can set special headers on individual requests to choose between old and new behavior and understand how the change affects them.
It’s very important for all developers to understand how to migrate through breaking changes so please read the full documentation about our deprecation process.
New Rich Text
Users in Asana can format text to style it with bolding or italics, or give it structure with lists or hyperlinks, but our existing support for this was difficult to use in the API. Worse, it was nearly impossible to parse links in Asana in a straightforward way (external hyperlinks as well as @-mentions to users / projects / tasks) and to understand to whom or where the link is referencing. To rectify this we are replacing rich text to provide better support for these features. Now it’s possible for integrations to parse and update a strict XML representation of rich text to use these features, including special attributes which provide information that had previously been complicated to find. For apps already using our rich text, this change will be managed by our deprecation framework and is available now for making the transition.
Asana is moving to string IDs
A upcoming breaking change that all apps must handle is the switch from integers to strings for object IDs in Asana. In order to help you transition, our API now returns a string
gid field everywhere that the integer
id field is returned. Integrations should use
gid to reference Asana objects moving forward. For more information, refer to our original post on string IDs and how to use our deprecation framework and for all the latest updates visit the announcement topic in the Asana Forum
Project Status Updates
When users post status updates for their projects it builds a history of how that project is progressing. Accessing this data can be useful for integrations that want to generate reports about these projects. Integrations can also give their users the ability to create a status update in the report without ever leaving the integration. To support these use cases you can now read the full history of status updates and create new ones through our API. Find more information in our API reference for project statuses.
Client libraries are now up to date with these features
With all the new features that we’ve released recently, we’ve also taken the time to support them in our official client libraries. Now is a good time to upgrade and start using the latest features of Asana’s API.