19 Sep 2016
Day 1 - Asana
After a false start last week, today I finally began my Programming Challenge: Five API Integrations in Five Days. Today’s integration was Asana, one of the most requested integrations. It wasn’t quite as quick and easy as Slack, but I was able to finish the Asana integration in one day, here’s how that day went:
Is this even possible?
As I said before, I’ve not even checked to see if any of my 5 chosen integrations have a REST API, so the first thing I did was dive into Asana’s documentation. Thankfully they do have a pretty decent REST API, with Oauth2 based authentication. This meant I could reuse a lot of code from existing integrations.
Once I’d familiarised myself with their API a bit, I set up an Asana account, and created a BugMuncher application.
A wild problem has appeared
So that I don’t ever expose BugMuncher’s private or public API keys for any of the third-party services with which it integrates, I proxy requests through the BugMuncher API server. Up until now I’d been embedding integration specific information into the redirect URL for OAuth integrations.
Asana decided to ruin that plan by requiring that the redirect URL specified exactly matches the one in the original application settings, where as every other API I’ve worked with only requires that the URL starts the same, ie: is on the same domain. Asana is so strict about this, that even adding a query string would cause the request to be rejected.
Having spent a few minutes fruitlessly trying to get round this restriction, I started to think I was going to have to create a completely custom OAuth flow for Asana in BugMuncher. Then I noticed
state parameter in Asana’s OAuth documentation.
I had seen this parameter in OAuth documentation before, but never really understood what it was for. Today I realised, and ended up feeling like a complete idiot in the process. Anything I send to Asana (or any OAuth provider) in the state parameter will be included unmodified in the response. I should have been using the state parameter all along, instead of trying to embed information in the redirect URL. Needless to say I’ll be updating all BugMuncher’s existing OAuth integrations to make use of this.
On the plus side I learned something new today, so that’s a bonus.
Now that I was using the state parameter, as was able to successfully authenticate with Asana, and started working on the actual API integration itself.
I needed to be able to fetch the authenticated user’s projects, create a task in one of those projects and attach the screenshot to the task.
Including unit and integration tests, I had the back end API side of things finished by 2:30pm. Stopping only for coffee at 10:15 and lunch at 12:30.
The front end part was largely painless, as I was able to re-use a lot of code, thanks to the fancy driver system. By 4:00pm the front end was finished and I had the whole setup working on my staging server.
I spent 15 minutes taking some screenshots and writing the documentation, before I was able to make the whole thing live.
After making the Asana integration live I ran some end-to-end tests to make sure it all worked properly, updated the BugMuncher homepage to list Asana as an integration, and then contacted Asana to find out how I can get BugMuncher included in their app directory. Everything was finished by 4:30 pm.
Total time taken: 7 hours
That’s it for today, tomorrow I tackle Pivotal Tracker.