Introduction
The fixx API is based on the concepts of REST and supports four key verbs to perform operations on fixx objects.
Example :
- GET /api/issues - Retrieve all issue objects
- GET /api/issues/1 - Retrieve issue 1
- POST /api/issues - Create a new issue by posting the values
- PUT /api/issues/1 - Edit/modify an existing issue by posting new values
- DELETE /api/issues/1 - Delete issue 1
The fixx API currently supports 2 output formats, XML and JSON. You can control the format the data is returned in by setting the Accept and Content-Type HTTP Header in your HTTP Request to either application/xml or application/json.
Authentication
Authentication to the fixx API is currently performed using an existing user account. The user account used to access the API will determine the permissions and objects you have access to. For example, if you authenticate with an administrator account, you will have the option to access and read any project or issue in the system, where as, if you authenticate with a client account, you get to see only projects/issues the client has access to.
fixx currently supports HTTP Basic Authentication, which means each HTTP request needs to be accompanied by the username and password to access fixx.
Note: Browser-based tools that access the API can use the JSESSIONID cookie but this is not officially documented nor supported.
Here is how you would authenticate using curl:
curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' \
-u user:password http://localhost:9000/api/projects
Projects
Get projects
GET /api/projects
Returns all available projects for the logged in user.
<projects>
<project>
.........
</project>
<project>
.........
</project>
<project>
.........
</project>
</projects>
Get specific project
GET /api/projects/{project_id}
<project>
<id>1</id>
<name>fixx</name>
<description>bug tracking and issue tracking for the enterprise</description>
<projectLead>Sarat Pediredla</projectLead>
<forceUsersToLogTime>false</forceUsersToLogTime>
<hideTimeLogsFromClient>false</hideTimeLogsFromClient>
<restricted>false</restricted>
<archived>false</archived>
</project>
Create a new project
POST /api/projects
Create a new project.
Returns the newly created project if the post is successful.
<project>
<name>fixx</name>
<description>Bug Tracking made simple</assignedTo>
<projectLead>1</projectLead>
<forceUsersToLogTime>false</forceUsersToLogTime>
<hideTimeLogsFromClient>false</hideTimeLogsFromClient>
<restricted>false</restricted>
<archived>false</estimatedTarchivedime>
</project>
Update a project
Update an existing project. To update a project without losing it's data, you need to ensure all the following attributes are included in the PUT request. Any other attribute not mentioned in the list below will be ignored or set to defaults.
Returns the updated project if the put is successful.
PUT /api/projects/{project_id}
<project>
<id>1</id>
<name>fixx</name>
<description>bug tracking and issue tracking for the enterprise</description>
<projectLead>1</projectLead>
<forceUsersToLogTime>false</forceUsersToLogTime>
<hideTimeLogsFromClient>false</hideTimeLogsFromClient>
<restricted>false</restricted>
<archived>false</archived>
</project>
Resolutions
Get all resolutions for a project
GET /api/projects/{project_id}/resolutions
<resolutions>
<resolution>
<id>1</id>
<name>Resolved - Won't fix</name>
</resolution>
<resolution>
..........
</resolution>
</resolutions>
Issue Types
Get all issue types for a project
GET /api/projects/{project_id}/issue-types
<issueTypes>
<issueType>
<id>1</id>
<name>Bug</name>
<description>A problem</name>
</issueType>
<issueType>
..........
</issueType>
</issueTypes>
Areas
Get all areas for a project
GET /api/projects/{project_id}/areas
<areas>
<area>
<id>1</id>
<name>Java</name>
<description>Java-related problems</name>
</area>
<area>
..........
</area>
</areas>
Versions
Get all versions for a project
GET /api/projects/{project_id}/versions
<versions>
<version>
<id>1</id>
<name>0.1</name>
<released>false</released>
</version>
<version>
..........
</version>
</version>
Get only released versions for a project
GET /api/projects/{project_id}/versions?type=fixfor
<versions>
<version>
<id>1</id>
<name>0.1</name>
<released>true</released>
</version>
<version>
..........
</version>
</version>
Issues
Get all issues in the system (with filtering, search & paging)
GET /api/issues?{querystring}
Returns all issues that match the specified filter or search in query string.
Filtering
To filter the issues returned by this resource, you can pass parameters in the query string to apply a filter (ex. ?qArea=1&qProject=1). You can also specify multiple values for a filter parameter by comma-seperating them (ex. ?qArea=1,2,3&qProject=1,2)
| Parameter | Filter applied | Acceptable Values |
|---|---|---|
| qProject | Project | Project ID |
| qArea | Area | Area ID |
| qResolution | Resolution | Resolution ID |
| qType | Issue Type | Issue Type ID |
| qAffected | Affected Version | Version ID |
| qFixFor | Fix For Version | Version ID |
| qAssignedTo | Assigned To | User ID |
| qCreatedBy | Created By | User ID |
| qWatcher | People watching an issue | User ID |
| qResolvedBy | Resolved By | User ID |
| qPriority | Priority | Priority ID |
| qStatus | Status | One of : "Open", "Resolved", "Closed", "All" |
| qCreatedOnLowerRange | Created On greater than provided value | Date string in the format of "dd/mm/yyyy" |
| qCreatedOnUpperRange | Created On less than provided value | Date string in the format of "dd/mm/yyyy" |
| qCreatedOnLowerRange | Created On less than provided value | Date string in the format of "dd/mm/yyyy" |
| qDueOnLowerRange | Due On greater than provided value | Date string in the format of "dd/mm/yyyy" |
| qDueOnUpperRange | Due On less than provided value | Date string in the format of "dd/mm/yyyy" |
| qResolvedOnLowerRange | Resolved On greater than provided value | Date string in the format of "dd/mm/yyyy" |
| qResolvedOnUpperRange | Resolved On less than provided value | Date string in the format of "dd/mm/yyyy" |
Sorting
You can sort filtered data by passing a parameter called qSortBy which accepts any of the values specified below. You can control the sort order by passing a parameter called qSortOrder where a value of 1 = Ascending order and 2 = Descending order.
- id
- priority
- type
- project
- title
- assignedTo
Free-text search
Alternative to filtering, you can apply a free-text search to the list of issues by passing a parameter called q with the free-text query. The current free-text search is based on Lucene and supports advanced search using wildcards and logical operators like AND or OR. Please read the documentation for Apache Lucene.
Note: You cannot apply a free-text search and filter at the same time. They are both mutually exclusive and a free-text search always overrides any applied filters.
Paging
You can control the number of issues returned by using parameters for paging called qCurrentPage to denote the current page and qPageSize to denote the maximum records to return in a page. The default page size is 50.
Get all issues for a project
GET /api/projects/{project_id}/issues
Returns all issues for a project identified by project_id
<issues>
<issue>
.........
</issue>
<issue>
.........
</issue>
<issue>
.........
</issue>
</issues>
Get specific issue
GET /api/issues/{issue_id}
Returns a specific issue identified by issue_id
<issue>
<id>1</id>
<title>Alpha issue in fixx</title>
<description>A test description</description>
<assignedTo>1</assignedTo>
<type>1</type>
<priority>1</priority>
<area>1</area>
<dueOn>2008-01-14T00:02:00Z</dueOn>
<createdBy>1</createdBy>
<estimatedTime>0</estimatedTime>
<closed>false</closed>
<hideFromClient>false</hideFromClient>
</issue>
Create a new issue
POST /api/issues
Create a new issue. Any attributes that are not passed in the post are set to defaults.
Returns the newly created issue if the post is successful.
<issue>
<title>.......</title>
<description>.........</description>
<assignedTo>1</assignedTo>
<type>1</type>
<priority>1</priority>
<area>1</area>
<dueOn>2008-01-14T00:02:00Z</dueOn>
<estimatedTime>0</estimatedTime>
<affected>1</affected>
<fixfor>2</fixfor>
<closed>false<closed>
<hideFromClient>false</hideFromClient>
</issue>
Update an existing issue
PUT /api/issues/{issue_id}
Update an existing issue. To update an issue without losing it's data, you need to ensure all the following attributes are included in the PUT request. Any attributes from the following list that are not passed in the put request are set to null. Any other attribute not mentioned in the list below will be ignored or set to defaults.
Returns the updated issue if the put is successful.
<issue>
<title>.......</title>
<description>.........</description>
<assignedTo>1</assignedTo>
<type>1</type>
<priority>1</priority>
<area>1</area>
<dueOn>2008-01-14T00:02:00Z</dueOn>
<estimatedTime>0</estimatedTime>
<affected>1</affected>
<fixfor>2</fixfor>
<resolution>1</resolution>
<resolvedBy>1</resolvedBy>
<resolvedOn>2008-01-14T00:02:00Z</resolvedOn>
<closed>false<closed>
<closedOn>2008-01-14T00:02:00Z</closedOn>
<hideFromClient>false</hideFromClient>
</issue>
Delete an existing issue
Delete an existing issue if it exists. Returns HTTP Status 200 if successful.
DELETE /api/issues/{issue_id}
Comments
Get all comments for an issue
GET /api/issues/{issue_id}/comments
Returns all comments for an issue identified by issue_id
<comments>
<comment>
<id>3</id>
<text>
This bug was reported by 2 people over the last week.
</text>
<createdAt>2008-12-23T18:35:02.045Z</createdAt>
<createdBy>1</createdBy>
<issue>1</issue>
</comment>
<comment>
............
</comment>
<comment>
............
</comment>
</comments>
Add a comment to an issue
POST /api/issues/{issue_id}/comments
Create a new comment on the issue specified by issue_id. Only the follow attributes are accepted on comment creation. Any other attribute will be ignored or set to defaults.
Returns the newly created comment if the post is successful.
<comment>
<text>Adding a comment through the API</text>
</comment>
Delete an existing comment
Delete an existing comment if it exists. Returns HTTP Status 200 if successful.
DELETE /api/issues/{issue_id}/comments/{comment_id}
Timelogs
Get all timelogs for an issue
GET /api/issues/{issue_id}/timelogs
Returns all timelogs for an issue identified by issue_id
<timelogs>
<timelog>
<id>3</id>
<effort>2</effort>
<description>Added new CSS code for this view</description>
<issue>1</issue>
<createdAt>2008-12-23T18:35:02.045Z</createdAt>
<createdBy>1</createdBy>
</timelog>
<timelog>
............
</timelog>
<timelog>
............
</timelog>
</timelogs>
Add a timelog to an issue
POST /api/issues/{issue_id}/timelogs
Create a new timelog on the issue specified by issue_id. Only the follow attributes are accepted on timelog creation. Any other attribute will be ignored or set to defaults.
Returns the newly created timelog if the post is successful.
<timelog>
<effort>2.5</effort>
<description>Did something interesting</description>
</timelog>
Delete an existing timelog
Delete an existing timelog from an issue if it exists. Returns HTTP Status 200 if successful.
DELETE /api/issues/{issue_id}/timelogs/{timelog_id}
Tags
Get all tags for an issue
GET /api/issues/{issue_id}/tags
Returns all tags for an issue identified by issue_id
<tags>
<tag>
<id>2</id>
<label>how to</label>
</tag>
<tag>
............
</tag>
<tag>
............
</tag>
</tags>
Add a tag to an issue
POST /api/issues/{issue_id}/tags
Create a new tag on the issue specified by issue_id. If the tag already exists, fixx will re-use it. Only the follow attributes are accepted on tag creation. Any other attribute will be ignored or set to defaults.
Returns the newly created tag if the post is successful.
<tag>
<label>bug</label>
</tag>
Delete an existing tag
Delete an existing tag from an issue if it exists. Returns HTTP Status 200 if successful.
DELETE /api/issues/{issue_id}/tags/{tag_id}
Changelogs
Get all changelogs for an issue
GET /api/issues/{issue_id}/changelogs
<changelogs>
<changelog>
<id>1</id>
<event>COMMENT_CREATED</event>
<comment>This has been reassigned to Mark.</comment>
<createdAt>2008-12-23T19:59:06.923Z</createAt>
<createdBy>1</createdBy>
</changelog>
<changelog>
..........
</changelog>
</changelogs>
Users
Get all users in the system
GET /users
<users>
<user>
<id>1</id>
<firstName>Sarat</firstName>
<lastName>Pediredla</lastName>
<username>sarat</username>
<email>sarat@email.com</email>
<phoneNumber>111111</phoneNumber>
<website>http://hedgehoglab.com</website>
<enabled>true</enabled>
</user>
<user>
..........
</user>
</users>
Get a specific user in the system
Allows you to pass either a user id or username to retrieve details.
GET /users/{user_id} or GET /users/{username}
<user>
<id>1</id>
<firstName>Sarat</firstName>
<lastName>Pediredla</lastName>
<username>sarat</username>
<email>sarat@email.com</email>
<phoneNumber>111111</phoneNumber>
<website>http://hedgehoglab.com</website>
<enabled>true</enabled>
</user>
Get all users assigned specifically to a project (only applicable to restricted projects)
GET /api/projects/{project_id}/users
<users>
<user>
<id>1</id>
<firstName>Sarat</firstName>
<lastName>Pediredla</lastName>
<username>sarat</username>
<email>sarat@email.com</email>
<phoneNumber>111111</phoneNumber>
<website>http://hedgehoglab.com</website>
<enabled>true</enabled>
</user>
<user>
..........
</user>
</users>
Get all clients assigned to a project
GET /api/projects/{project_id}/clients
<users>
<user>
<id>1</id>
<firstName>Sarat</firstName>
<lastName>Pediredla</lastName>
<username>sarat</username>
<email>sarat@email.com</email>
<phoneNumber>111111</phoneNumber>
<website>http://hedgehoglab.com</website>
<enabled>true</enabled>
</user>
<user>
..........
</user>
</users>
Get all users watching an issue
GET /api/issues/{issue_id}/watchers
<users>
<user>
<id>1</id>
<firstName>Sarat</firstName>
<lastName>Pediredla</lastName>
<username>sarat</username>
<email>sarat@email.com</email>
<phoneNumber>111111</phoneNumber>
<website>http://hedgehoglab.com</website>
<enabled>true</enabled>
</user>
<user>
..........
</user>
</users>
Subscribe a user to watch issue notifications
PUT /api/issues/{issue_id}/watchers/{watcher_id}
Returns the updated list of watchers if successful.
Priorities
Get all priorities in the system
GET /priorities
<priorities>
<priority>
<id>1</id>
<name>Minor</name>
<description>Minor task</description>
<weight>1</weight>
</priority>
<priority>
..........
</priority>
</priorities>
Get a specific priority in the system
GET /priorities/{priority_id}
<priority>
<id>1</id>
<name>Minor</name>
<description>Minor task</description>
<weight>1</weight>
</priority>