Venting about the API system!

[avesta]

I am writing today in the hopes of getting the community’s feedback on whether I’m crazy or not, and hopefully we will even affect the way Asana manages their API.

When you(Asana) make updates to the API, even when tiny updates, it somehow always causes problems in our company’s day-to-day. Frankly, it also hurts the morale of our small development team to continuously have to update our code. For example, today, all of our scripts that connect to the Asana API stopped working. To fix our errors, I found out that I now had to replace “id” with “gid”. Thats ALL I had to do. While a quick fix, it is absurd that this happened in the first place.

It is very important that I have an understanding and empathy for why you keep making changes to the API like this. I have some questions, please kindly review them:

1. Why dont you have an API system that has versions, and allows us to upgrade versions on our own time?
2. Should I assume, every time you make an update that causes an error in my code, its because you have a huge security flaw that you had to fix? If it isnt security related, why make the change at all knowing that many companies will have to rewrite their scripts?
3. Why did you feel the need to drop “id” from the API response on project info and task info? I understand it was a duplicate of “gid”, but is that really the only reason?

I am honestly beyond frustrated, because we run a small company and I’m literally tired of being called out of meetings to fix errors like this. I am not an expert developer. But I have seen competitors, well funded with teams of developers just like you, manage API systems in a much easier way for me. They create API versions, and allow us to upgrade the API version on our own time, with an understanding that teams around the globe depend on STABILITY in their API calls.

Despite my anger and frustration, and the fact that we are a tiny subscriber to you money-wise, please read this message with open eyes and seriously consider the position we are in as a 2-man development team.

Thank you for reading.

Reply

[Phil_Seeman]

Hi @avesta,

FYI the answers to all 3 of your questions can be found in the Developers & API section of the forum.

I’ll let the Asana API team respond with more details about this string-ID change if they choose to. The one thing I feel a need to point out here is that the API team provided us developers with an incredible amount of advance notice, multiple notifications, preemptive warnings, etc. about this change.

They first announced this change over a year ago on Aug. 21, 2018:

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

Hi everyone! Unfortunately this is one of my announcements that doesn’t include a new feature launch, sorry. However, this one is much more important to read, as it is guaranteed to cause your code to break. Asana currently uses numerical IDs for all references, but we are running out of them. Once we surpass 253, JavaScript loses precision and is no longer able to accurately represent every ID. You can observe this by opening up a JavaScript console and seeing that 2*…

Since then, over the past 14 or so months, they’ve continually kept developers apprised about it. Several times they temporarily made the change for short spurts of time (one hour, one day, etc.) to help surface the issue for developers that weren’t previously aware of it. They delayed making the change permanent several times, to allow even more opportunity for developers to update their code. I recommend reading through that referenced thread above for more info.

The one strong concrete recommendation I can make to you is to visit this Developers section of the forum periodically, to insure that you’re keeping abreast of upcoming API changes, as the API team always provides ample advance notice of them here.

Personally I make it a policy that whenever I create software that integrates with third-party software, I make sure to always check the third-party company’s support forum periodically, for this reason - to avoid unnecessary surprises!

[Ross_Grambo]

Hey @avesta,

I’ve been working here as a Developer Advocate for almost a year. I’ll give my best shot to answer these questions.

Why dont you have an API system that has versions, and allows us to upgrade versions on our own time?

Implementing a versioned API is a huge infrastructure investment, especially when your product is constantly updating and adding new features. When I first started working here, I thought having a non-versioned API was crazy. But the more I work here, the more I understand why we haven’t made that jump.

That being said, Asana does offer a framework for dealing with these upgrades. Asana’s deprecation framework.

When the API needs to deprecate something, whether it be for security, stability, or product changes, we start sending Asana-Change headers with responses. These headers notify developers when your requests might be affected by a deprecation in the future. Then, over the course of the pre-activation window (~a few months), you can opt_in to using the new functionality, or when we reach the activation date, you can still opt_out and still use the old functionality during the post-activation window.

This gives developers a window to upgrade on their own time. Because each deprecation essentially becomes a versioned API during that time frame, where you’re either using the old or new functionality.

If you use the latest client libraries, we by default surface these warnings for you!

If I was managing an app, I’d listen to that asana-change header, and if I saw anything, I’d assign myself a task to check it out.

Should I assume, every time you make an update that causes an error in my code, its because you have a huge security flaw that you had to fix? If it isnt security related, why make the change at all knowing that many companies will have to rewrite their scripts?

I very much agree with this concern. While the issues are not always security related (stability & product changes as well), I assure you that we don’t take deprecations lightly, and if the API is issuing a new deprecation, there was good reasoning as to why we needed it to happen.

Why did you feel the need to drop “id” from the API response on project info and task info? I understand it was a duplicate of “gid”, but is that really the only reason?

From my understanding, this change was mainly due to “id” being no longer correct. Asana moved from using numeric ids to using string ids. “id” was a number. While untyped languages might have been able to get away with using id for a little longer, typed languages would fail when we started returning a string instead of a number in the “id” field.

We were returning both gid and id since February until we activated the change, and id was removed (if you currently send the opt_out header, you would still be getting “id” in the response).

Thoughts

I think the biggest issue with our deprecation framework is that it’s not as in-your-face as a versioned API. A versioned API has the version in the URL so you’re kind of forced to acknowledge which behavior you’re choosing to use. Asana has nice version-like behavior, but it’s hidden as headers. So developers who don’t know about it, don’t get to use it.

I don’t have the context to give exact answers, but I hope this helps! I’m happy to answer more questions as best I can.

[avesta]

You two have been very helpful and kind with your responses. They were VERY helpful. Thanks Ross for taking the time to share your experiences. I understand better now and I am willing to continue to learn about the Asana API system, check the development forum periodically, and am interested to see how Asana’s development team+infrastructure continues to grow and change.

Thanks again!

I have to say, other than such frustrations, Asana meets our needs and the API being easily accessible to small teams without complicated authentication systems is a gem.