The new DoneDone: how the API is changing

As part of the updates to DoneDone we're making, whose release is fast approaching, we're revamping the way the API is implemented and how developers will interact with the system. Due to the changes, this means that the old API will no longer be available as of October 1st, 2011 and that any integration you've built for use with DoneDone will need to be revamped. While this seems like a major bummer, the old API was difficult to use and limited in its capabilities. The new API is quicker, easier, and much more dynamic.

In the beginning, there was SOAP

We opted to build it using SOAP for our first API, which at the time was easy for us to spin up and deploy. Unfortunately, SOAP has proven to be difficult to integrate with for most of our users and it is now evident that a REST-like API is better suited to how developers consume data between applications. SOAP, while offering strongly typed objects for communication back and forth, is bandwidth heavy and resource heavy on the implementation side for both the service provider (us) and the consumer (you). The way we handled authentication meant that most of our non-windows users needed to jump through a few hoops to integrate successfully. Updating our web service method signatures meant that developers would need to update their code to point to a new WSDL, which meant we were more likely than not hesitant to update the API, which meant that it stagnated.

Now there will be REST

The new API will be built to avoid some of these problems. REST provides us with a way to easily make updates to the web services and deploy them in a way that doesn't immediately deprecate old code for our users. All requests will be made with either a GET, POST, PUT, or DELETE verb and you will receive a response with the correct HTTP Status code sent depending on whether it was successful or if a problem occurred. We're also taking a page out of other inspired APIs and simplifying the authentication mechanism. Now, you'll authenticate your identity and our identity in two ways:

1. You'll pass your credentials in on any requests that require your identity via a standard HTTP Authentication header. Since DoneDone runs over SSL, your credentials are safely transmitted. This will allow you to build applications using the DoneDone API and allow users to provide their own credentials, without you having to manage any session or cookie information on your side.
2. Taking a page out of the Twilio API handbook, you can verify that requests are indeed coming from us (and we can verify that they're really coming from you!) by calculating the hash of the message you're sending to us and signing it with your secret API key. We'll respond to requests and include a calculated hash for the message signed with your API key, which you can confirm against your expectations.

Early testing

The initial release of this new API will be rolled out to a sandbox environment by 09/26/2011 so you can begin transitioning any code you've written that integrated with the old API over to the new one. We'll initially be supporting the same methods as we provided in the first API, at a minimum, and provide new methods that make use of the new features available in the new DoneDone soon afterward.

Getting a head start

For those of you itching to get started in advance of the sandbox release, the old API web methods will map to the new URL scheme as follows, where all requests are made to: https://youraccountdomain.mydonedone.com/IssueTracker/API/MethodName/{parameters}

• Login() -> No longer used.
• Logout() -> No longer used.
• GetProjects() -> [GET] /Projects
• GetPriorityLevels() -> [GET] /PriorityLevels
• GetPeopleInProject()-> [GET] /PeopleInProject/{project_id}
• GetIssuesInProject()-> [GET] /IssuesInProject/{project_id}
• DoesIssueExist()-> [GET] /DoesIssueExists/{project_id}/{issue_id}
• GetIssue()-> [GET] /Issue/{project_id}/{issue_id}
• GetListOfPotentialStatusesForIssue()-> [GET] /PotentialStatusesForIssue/{project_id}/{issue_id}
• GetListOfPeopleForIssueReassignment()-> [GET] /PeopleForIssueReassignment/{project_id}/{issue_id}
• CreateIssueForProject()-> [POST] Issue/{project_id} posting the data required to create an issue
• AddCommentToIssue()-> [POST] /Comment/{project_id}/{issue_id} posting the data required to create a comment
• ReassignIssue()-> [PUT] /Issue/{project_id}/{issue_id} putting the data required to reassign the issue in the body
• SetIssueStatus()-> [PUT] /Issue/{project_id}/{issue_id} putting the data required to update the issue status in the body
• CloseIssue()-> [PUT] /Issue/{project_id}/{issue_id} putting the data required to update the issue status to closed in the body
• ReopenIssue()-> [PUT] /Issue/{project_id}/{issue_id} putting the data required to update the issue status to open in the body

Fewer, but better methods

As you may notice, there are fewer methods in this scheme but they have the ability to perform multiple functions, depending on the request body. The request body will generally be made up of JSON objects and the return value will also be a JSON object. This allows for a greater number of platforms to integrate with our new API and will also allow you to handle the objects however you choose - passing partial objects in when you want to instead of building an entire object, for example, since JSON isn't strongly typed the way we were using SOAP in the old API.

Wrap up

The changes we're making to the API will make things easier and more extensible and while you'll need to make some changes to how you access your data, in the long run, you'll have a lot more possibilities in terms of what you do with it.We can't say it enough. We're here to support everyone while we transition to the newer, faster DoneDone. Here's how you can get in contact:Twitter: http://www.twitter.com/getdonedoneForums: http://www.getsatisfaction.com/donedoneEmail: accounts[at]mydonedone.com