Customizing & Extending DoneDone

Developer’s API

Enabling the API

We offer a developer API which allows you to work with project and issue data for use in your own applications.  You can enable the API on a per-project basis by going to the Project Settings section of a project, as shown below.

Enable The API

Security

To make any calls to the API, provide your username and API Token (or password) via an HTTP Basic authentication header. It will look something like…

Authorization: Basic {XXXXXX}

…where {XXXXXX} is your Base64-encoded username:APIToken or username:password. The API Token is available on your DoneDone Profile page. All requests go over SSL, so your credentials are safe.

All requests are made to:
https://{YourDomain}.mydonedone.com/IssueTracker/API/{MethodName}/{Parameters}

Methods

Get All Projects

URL: [GET] /Projects/{load_with_issues}

Returns all active projects that you have permission to access. The parameter load_with_issues is optional. If provided, the value must be true or false. Passing true will load all projects as well as all of their active issues. It is a potentially heavy call, so use it sparingly.

[
    {
        "ID":123,
        "Name":"Acme Website Project",
        "Issues":null
    },
    {
        "ID":456,
        "Name":"Proj 2",
        "Issues":null
    }
]

Get Priority Levels

Returns all priority levels within DoneDone. You will pass the ID of the priority level when creating or editing issues.

URL: [GET] /PriorityLevels

[
   {
      "ID":1,
      "Value":"Low"
   },
   {
      "ID":2,
      "Value":"Medium"
   },
   {
      "ID":3,
      "Value":"High"
   },
   {
      "ID":4,
      "Value":"Critical"
   }
]

Get People in a Project

Returns all people within a project. You will pass the ID of the person to denote the fixer or tester when creating or re-assigning issues.

URL: [GET] /PeopleInProject/{project_id}

[
   {
      "ID":123,
      "Value":"Ka Wai Cheung"
   },
   {
      "ID":456,
      "Value":"Jeremy Kratz"
   }
]

Get Active Issues in a Project

Returns all active issues within a project.

URL: [GET] /IssuesInProject/{project_id}

[
   {
      "PriorityLevel":"Low",
      "State":"Open",
      "LastUpdatedDate":"/Date(1314996892513)/",
      "LastViewedDate":null,
      "CreateDate":"/Date(1314996892513)/",
      "DueDate":"/Date(1314996892513)/",
      "Title":"A fun sample issue",
      "OrderNumber":5,
      "ProjectID":123,
      "Tester":{
         "ID":123,
         "Value":"Ka Wai Cheung"
      },
      "Resolver":{
         "ID":456,
         "Value":"Jeremy Kratz"
      },
      "Creator":{
         "ID":123,
         "Value":"Ka Wai Cheung"
      }
   }
]

Check Issue Existence

Checks whether an issue with a given number in a project exists.

URL: [GET] /DoesIssueExist/{project_id}/{order_number}

{
   "IssueExists":true
}

Get Allowed Issue Statuses

Returns all allowed statuses that an issue can be updated to, given its current status and your role in the account. You must pass the ID of the issue status when editing an issue. If you are an administrator in the account, this will also return a list of all possible issue statuses. Administrators have the privilege of overriding an issue’s status to any status.

URL: [GET] /PotentialStatusesForIssue/{project_id}/{order_number}

{
   "PotentiallyAllowedStatusesForIssue":[
      {
         "ID":13,
         "Value":"In progress"
      },
      {
         "ID":14,
         "Value":"Not an issue"
      },
      {
         "ID":15,
         "Value":"Not reproducible"
      },
      {
         "ID":16,
         "Value":"Missing information"
      },
      {
         "ID":19,
         "Value":"Ready for retest"
      },
      {
         "ID":21,
         "Value":"Closed"
      }
   ],
   "AllStatusesSinceYouAreAnAdmin":[
      {
         "ID":12,
         "Value":"Open"
      },
      {
         "ID":13,
         "Value":"In progress"
      },
      {
         "ID":14,
         "Value":"Not an issue"
      },
      {
         "ID":15,
         "Value":"Not reproducible"
      },
      {
         "ID":16,
         "Value":"Missing information"
      },
      {
         "ID":17,
         "Value":"Pushed back"
      },
      {
         "ID":18,
         "Value":"Ready for next release"
      },
      {
         "ID":19,
         "Value":"Ready for retest"
      },
      {
         "ID":20,
         "Value":"Fix not confirmed"
      },
      {
         "ID":21,
         "Value":"Closed"
      }
   ]
}

Get Issue Details

Returns the various details of an issue.

URL: [GET] /Issue/{project_id}/{order_number}

{
   "Title":"A really simple issue",
   "ProjectTitle":"Acme Website Project",
   "ProjectID":123,
   "OrderNumber":456,
   "Description":"Just fix this really simple issue.",
   "DueDate":"/Date(1314996892513)/",
   "PriorityLevel":"Low",
   "PriorityLevelID":1,
   "IssueState":"Open",
   "IssueStateID":12,
   "Resolver":{
      "ID":123,
      "Value":"Ka Wai Cheung"
   },
   "Tester":{
      "ID":456,
      "Value":"Jeremy Kratz"
   },
   "Creator":{
      "ID":1,
      "Value":"Craig Bryant"
   },
   "Watchers":[
      {
         "ID":4,
         "Value":"Michael Sanders"
      },
      {
         "ID":26,
         "Value":"Ka Wai Cheung"
      }
   ],
   "Tags":[
      {
         "ID":122,
         "Value":"api"
      }
   ],
   "UserRoleIDs":[
      3,
      4,
      5
   ],
   "CompaniesAndPeopleOnIssue":[
      {
         "ID":1,
         "Name":"We Are Mammoth",
         "People":[
            {
               "ID":1,
               "FirstName":"Mustafa",
               "LastName":"Shabib",
               "AccountRoleID":1,
               "EmailAddress":"mustafa.shabib@wearemammoth.com"
            }
         ]
      },
      {
         "ID":102,
         "Name":"Chicago Cubs",
         "People":[
            {
               "ID":162,
               "FirstName":"Andre",
               "LastName":"Dawson",
               "AccountRoleID":1,
               "EmailAddress":null
            }
         ]
      }
   ],
   "TesterResolverAndWatcherIDs":[
      2,
      3,
      4,
      26
   ],
   "Attachments":[
      {
         "ID":0,
         "FileUpload":"http://c3362733.r33.cf0.rackcdn.com/7a72328a-00f2-4985-80a8-6f9da3043f31_smalla.jpg",
         "Bytes":162597.00,
         "RelatedActionableItemHistoryID":58036,
         "RelatedActionableItemHistory":null
      }
   ],
   "Histories":[
      {
         "ID":57406,
         "AvatarURL":"http://c3363003.r3.cf0.rackcdn.com/e48bd3f6-d9be-457c-8cf3-901e99a8b8cf_kc.jpg",
         "CreateDate":"/Date(1314996892513)/",
         "Action":"Craig Bryant created the issue.",
         "Description":"Assigned to *Ka Wai Cheung* as the resolver, and to *Mustafa Shabib* as the tester. This issue is marked as *Low*.",
         "HistoryType":11,
         "Attachments":[
         ]
      }
   ]
}

Get People For Issue Assignment

Returns a list of people that an issue can be re-assigned to as a fixer or tester.

URL: [GET] /PeopleForIssueAssignment/{project_id}/{order_number}

[
   {
      "ID":123,
      "Value":"Ka Wai Cheung"
   },
   {
      "ID":456,
      "Value":"Jeremy Kratz"
   }
]

Create Issue

Creates a new issue for a project.

URL: [POST] /Issue/{project_id}

POST Data (parameter name, type, required or optional):

  • title: string, required.
  • description: string, optional.
  • due_date: date, optional.
  • tags: comma-delimited string, optional.
  • priority_level_id: short, required. Get a list of valid priority levels from the method documented above.
  • resolver_id: int, required. Get a list of people on this project from the method documented above.
  • tester_id: int, required. Get a list of people on this project from the method documented above.
  • watcher_ids: comma delimited string of user IDs. Optional.

Files can be attached by posting the form with the content-type multipart/form-data.

{
   "IssueID":128,
   "IssueURL":"http://yourdomain.mydonedone.com/issuetracker/projects/1234/issues/5",
   "SuccesfullyAttachedFiles":"true"
}

Create Comment

Inserts a new comment into an issue.

URL: [POST] /Comment/{project_id}/{order_number}

Post Data (parameter name, type, required or optional):

  • comment: string, required.
  • people_to_cc_ids: comma delimited string of people’s ids. Optional.

Files can be attached by posting the form with the content-type multipart/form-data.

{
   "CommentURL":"http://yourdomain.mydonedone.com/issuetracker/projects/1234/issues/5#history-12345",
   "SuccesfullyAttachedFiles":"true"
}

Edit Issue

URL: [PUT] /issue/{project_id}/{order_number}

Updates the due date, tags, title, description, priority level, status, resolver, or tester of an issue. You need to be an administrator to use this call.

If you provide no due date for an issue that already has a due date, the date will be set to NULL. If you don’t want to change an issue’s due date, be sure to provide its current date in your PUT data.

If you wish to retain the tags for an issue and update it by adding one new tag, then you’ll have to provide all of the existing tags as well as the new tag in your tags parameter.

For all other parameters, the value you pass will be used to update the issue. If you wish to keep the value that’s already on an issue, then do not provide the parameter in your PUT data.

PUT Data (parameter name, type):

  • title: string, optional.
  • description: string, optional.
  • due_date: date, optional. If left blank, the due date will be removed from this issue.
  • tags: comma-delimited string, optional.
  • priority_level_id: short, optional. Get a list of valid priority levels from the method documented above.
  • state_id: short, optional. Get a list of valid states that this issue can transition to from the method documented above.
  • resolver_id: int. Get a list of people on this project from the method documented above.
  • tester_id: int. Get a list of people on this project from the method documented above.
{
   "IssueURL":"http://yourdomain.mydonedone.com/issuetracker/projects/1234/issues/5"
}

Client Libraries

DoneDone’s client libraries provide an easy-to-use interface for accessing the API calls. We currently offer client libraries in three different languages: C#, PHP, and Python. To use these libraries with a DoneDone project, you will need to enable the API option under the Project Settings page.

You can download the DoneDone client libraries from GitHub here.

Each of the libraries provides a generic method to access DoneDone’s IssueTracker API and shorthands to call the corresponding API methods directly. The result will be a JSON string returned by the server.

C#

Download the C# client library.

Initializing
using DoneDone;
var domain ="YOUR_COMPANY_DOMAIN";/* e.g. wearemammoth */
var token ="YOUR_API_TOKEN";
var username ="YOUR_USERNAME";
var password ="YOUR_PASSWORD";
var issueTracker =newDoneDone.IssueTracker(domain, token, username, password);
Calling the API
issueTracker.API("GetProjects");
/* This will get all your projects with the API enabled. */
issueTracker.GetProjects();
/* This is the same as the above. */

PHP

Download the PHP client library.

Initializing
require_once "DoneDone.php";
$domain ="YOUR_COMPANY_DOMAIN";/* e.g. wearemammoth */
$token ="YOUR_API_TOKEN";
$username ="YOUR_USERNAME";
$password ="YOUR_PASSWORD";
$issueTracker =newIssueTracker($domain, $token, $username, $password);
Calling the API
$issueTracker->API("GetProjects");
/* This will get all your projects with the API enabled. */
$issueTracker->getProjects();
/* This is the same as the above. */

Python

Download the Python client library.

Initializing
fromDoneDoneimportIssueTracker
domain ="YOUR_COMPANY_DOMAIN"#e.g. wearemammoth
token ="YOUR_API_TOKEN"
username ="YOUR_USERNAME"
password ="YOUR_PASSWORD"
issueTracker =IssueTracker(domain, token, username, password)
Calling the API
issueTracker.API("GetProjects")
#This will get all your projects with the API enabled.
issueTracker.getProjects()
#This is the same as the above.

Responses

All responses will contain JSON-encoded data, with the response content type set to application/json.

Successes

200 – OK – The requested data or a success message with relevant details on POST and PUT requests will be provided as JSON encoded data described above.

Errors

Any request may respond with the following errors, each of which also provides some additional details (if any) as a simple JSON object with a message.

400 – Invalid – You are missing a required parameter or sending an invalid value for a parameter (an integer where a short was expected, for example). Check what you’re sending to the API compared to what’s expected in this documentation.

401 – Unauthorized – You need to provide correct credentials via the basic authentication header.

403 – Forbidden – You’re authenticated, but you are not authorized to perform the request.

404 – Not Found – We can’t find whatever you asked for (bad method, no issue found, no project found, etc.).

409 – Conflict – You’ve made too many requests to the same resource. You can only make 1000 requests from the same IP address per hour. We may adjust this rate limit in the future. When you receive this response, check the Retry-After header for how many seconds you have to wait until you are permitted to make requests again.

500 – Internal error – We did something wrong. Let us know on our support page.

Example Error Response

Here’s an example 404 response when attempting to update an issue that does not exist.

< HTTP/1.1404NotFound
< Server: ASP.NET DevelopmentServer/9.0.0.0
< Date:Mon,26Sep201118:38:14 GMT
< Cache-Control:private
< Content-Type: application/json; charset=utf-8
< Content-Length:26
< Connection:Close
<
{"Message":"Not found."}