{panel:title=TOC|titleBGColor=#F7D6C1|bgColor=#FFFFFF}
{toc:style=disc|indent=20px}
{panel}
Since QuickBuild 4.0, you can retrieve issues via RESTful APIs. The base URI for changes RESTful APIs is:
{code}
/rest/{tracker}
{code}
Here, tracker is the type of your issue tracker, in QuickBuild, includes:
* Jira - /rest/jira
* Trac - /rest/trac
* Bugzilla - /rest/bugzilla
below, we will use $baseURI to represent the URI: /rest/\{tracker}.
h3. List all supported APIs
||URI||Response Type||Params||
|$baseURI/help|_text/html_| |
h3. Get the data version of issues
||URI||Response Type||Params||
|$baseURI/version|_text/plain_| |
h3. Retrieve the issues related to a configuration
*Get the size*
||URI||Response Type||Params||
|$baseURI/size/\{configuration}|_text/plain_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here, if you want to specify a configuration path, you need add prefix PATH:, for example, _PATH:root/My/DEV_. *SINCE 5.0.14*, specify the configuration path directly, for example root/My/DEV, no need PATH: prefix anymore.
* *build* - QUERY_PARAM
The id of a specific build.
* *from_build* - QUERY_PARAM
Specify the from build when finding changes in a build range.
* *to_build* - QUERY_PARAM
Specify the to build when finding changes in a build range.|
for example, below url will retrieve the count of JIRA issues in a specified build:
{code}
http://quickbuild:8810/rest/jira/size/PATH:root%2FMy%2FDEV?build=100
Since 5.0.14
http://quickbuild:8810/rest/jira/size/root/My/DEV?build=100
{code}
or find issue count in a build range:
{code}
http://quickbuild:8810/rest/jira/size/19?from_build=100&to_build=200
{code}
*Retrieve the issues*
||URI||Response Type||Params||
|rest/jira/issues/\{configuration}|_text/xml_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here, if you want to specify a configuration path, you need add prefix PATH:, for example, PATH:root/My/DEV. *Since 5.0.14*, specify the configuration path directly, no PATH: prefix any more.
* *build* - QUERY_PARAM
Specify the build id you want.
* *from_build* - QUERY_PARAM
Specify the from build when finding changes in a build range.
* *to_build* - QUERY_PARAM
Specify the to build when finding changes in a build range.
* *offset* - QUERY_PARAM
Specify the first record when iterate the records, by default, the offset is 0
* *limit* - QUERY_PARAM
Specify the total records you want to retrieve, by default, the limit is 50
* *asc* - QUERY_PARAM
Boolean type, specify order by issue key ascendent or descendent, by default, it is ascendent.|
For example, below example retrieves the first 50 issues of build 100:
{code}
http://quickbuild:8810/rest/jira/issues/19?build=100
{code}
the response looks like:
{code}
<report name="issues" version="0.0" locale="en_US">
<row ID="15" issueKey="TST-23" buildId="321" issueType="New Feature" summary="2-phase load components" status="Resolved" priority="Major" created="2011-06-03T14:58:47.445+08:00" updated="2011-06-03T15:27:39.418+08:00" resolution="Fixed" assignee="admin" reporter="admin" modifications="3">
<changeIds>
913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943,f090cd04725c5551f8a439fe0a53591193ea79c3
</changeIds>
<repositories>hg,hg</repositories>
</row>
... ...
</report>
{code}
Each row element is a record of an issue related to a specified build, the data structure is:
{code}
class Issue {
Long ID; // No use, only used in QuickBuild internally
String issueKey;
Long buildId;
String issueType;
String summary;
String status;
String priority;
Date created; // Formated in ISO8601
Date updated;
String resolution;
String assignee;
String reporter;
int modifications; // related modifications
String changeIds; // related change set ids in CSV format
String repositories; // related repository names in CSV format
{code}
h3. Retrieve the builds of an issue
*Before 5.0.14:*
||URI||Response Type||Params||
|$baseURI/builds/\{configuration}/\{issuekey}/|_text/xml_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here, if you want to specify a configuration path, you need add prefix PATH:, for example, _PATH:root/My/DEV_.
* *issuekey* - PATH PARAM
The issue key you want to search.
* *count* - QUERY_PARAM
Specify at most how many records you want. If not specified, all records found will return.|
{code}
http://quickbuild:8810/rest/jira/builds/5/QB-123
{code}
*Since 5.0.14*
||URI||Response Type||Params||
|$baseURI//\{issuekey}/builds/\{configuration}|_text/xml_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here, or specify the configuration path
* *issuekey* - PATH PARAM
The issue key you want to search.
* *count* - QUERY_PARAM
Specify at most how many records you want. If not specified, all records found will return.|
{code}
http://quickbuild:8810/rest/QB-123/jira/builds/5
or
http://quickbuild:8810/rest/QB-123/jira/builds/root/My/DEV
{code}
The response looks like:
{code}
<list>
<build>
<id>321</id>
<version>1.0.15</version>
<status>SUCCESSFUL</status>
<beginDate>2011-06-10T17:11:35.662+08:00</beginDate>
<duration>3409</duration>
<scheduled>false</scheduled>
<requester>Administrator</requester>
<deleted>false</deleted>
</build>
... ...
</list>
{code}
Here, the build element is just a fragment of the build object in QuickBuild, if you need more detailed information about the build, please use [build RESTful API].
h3. Retrieve the changes of an issue
*Before 5.0.14*
||URI||Response Type||Params||
|$baseURI/changes/\{configuration}/\{issuekey}|_text/xml_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here, if you want to specify a configuration path, you need add prefix PATH:, for example, PATH:root/My/DEV
* *key* - PATH_PARAM
The issue key you want to search.
* *count* - QUERY_PARAM
Specify at most how many records you want. If not specified, all records found will return.|
{code}
http://quickbuild:8810/rest/jira/changes/5/TST-123
or
http://quickbuild:8810/rest/jira/changes/PATH:root/My Dev/TST-123
{code}
*Since 5.0.14*
||URI||Response Type||Params||
|$baseURI/\{key}/changes/\{configuration}|_text/xml_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here. You can also specify the configuration path directly
* *key* - PATH_PARAM
The issue key you want to search.
* *count* - QUERY_PARAM
Specify at most how many records you want. If not specified, all records found will return.|
{code}
http://quickbuild:8810/rest/jira/TST-123/changes/5
or
http://quickbuild:8810/rest/jira/TST-123/changes/root/My/DEV
{code}
The response looks like:
{code}
<list>
<changeset>
<user>steve</user>
<date>2011-05-31T03:45:55.000+08:00</date>
<id>f090cd04725c5551f8a439fe0a53591193ea79c3</id>
<repositoryName>hg</repositoryName>
<repositoryType>Mercurial</repositoryType>
<additional>13</additional>
<buildId>321</buildId>
<comment>
add a big file to related to issue TST-23, TST-24 TST-25
</comment>
<modifications>
<modification>
<action>ADD</action>
<path>big.java</path>
<edition>f090cd04725c5551f8a439fe0a53591193ea79c3</edition>
<previousEdition>c11a08aa7525a01e35239b8b6f34d4f8f3bf770b</previousEdition>
<additional>13</additional>
</modification>
</modifications>
</changeset>
... ...
</list>
{code}
h3.
{toc:style=disc|indent=20px}
{panel}
Since QuickBuild 4.0, you can retrieve issues via RESTful APIs. The base URI for changes RESTful APIs is:
{code}
/rest/{tracker}
{code}
Here, tracker is the type of your issue tracker, in QuickBuild, includes:
* Jira - /rest/jira
* Trac - /rest/trac
* Bugzilla - /rest/bugzilla
below, we will use $baseURI to represent the URI: /rest/\{tracker}.
h3. List all supported APIs
||URI||Response Type||Params||
|$baseURI/help|_text/html_| |
h3. Get the data version of issues
||URI||Response Type||Params||
|$baseURI/version|_text/plain_| |
h3. Retrieve the issues related to a configuration
*Get the size*
||URI||Response Type||Params||
|$baseURI/size/\{configuration}|_text/plain_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here, if you want to specify a configuration path, you need add prefix PATH:, for example, _PATH:root/My/DEV_. *SINCE 5.0.14*, specify the configuration path directly, for example root/My/DEV, no need PATH: prefix anymore.
* *build* - QUERY_PARAM
The id of a specific build.
* *from_build* - QUERY_PARAM
Specify the from build when finding changes in a build range.
* *to_build* - QUERY_PARAM
Specify the to build when finding changes in a build range.|
for example, below url will retrieve the count of JIRA issues in a specified build:
{code}
http://quickbuild:8810/rest/jira/size/PATH:root%2FMy%2FDEV?build=100
Since 5.0.14
http://quickbuild:8810/rest/jira/size/root/My/DEV?build=100
{code}
or find issue count in a build range:
{code}
http://quickbuild:8810/rest/jira/size/19?from_build=100&to_build=200
{code}
*Retrieve the issues*
||URI||Response Type||Params||
|rest/jira/issues/\{configuration}|_text/xml_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here, if you want to specify a configuration path, you need add prefix PATH:, for example, PATH:root/My/DEV. *Since 5.0.14*, specify the configuration path directly, no PATH: prefix any more.
* *build* - QUERY_PARAM
Specify the build id you want.
* *from_build* - QUERY_PARAM
Specify the from build when finding changes in a build range.
* *to_build* - QUERY_PARAM
Specify the to build when finding changes in a build range.
* *offset* - QUERY_PARAM
Specify the first record when iterate the records, by default, the offset is 0
* *limit* - QUERY_PARAM
Specify the total records you want to retrieve, by default, the limit is 50
* *asc* - QUERY_PARAM
Boolean type, specify order by issue key ascendent or descendent, by default, it is ascendent.|
For example, below example retrieves the first 50 issues of build 100:
{code}
http://quickbuild:8810/rest/jira/issues/19?build=100
{code}
the response looks like:
{code}
<report name="issues" version="0.0" locale="en_US">
<row ID="15" issueKey="TST-23" buildId="321" issueType="New Feature" summary="2-phase load components" status="Resolved" priority="Major" created="2011-06-03T14:58:47.445+08:00" updated="2011-06-03T15:27:39.418+08:00" resolution="Fixed" assignee="admin" reporter="admin" modifications="3">
<changeIds>
913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943,f090cd04725c5551f8a439fe0a53591193ea79c3
</changeIds>
<repositories>hg,hg</repositories>
</row>
... ...
</report>
{code}
Each row element is a record of an issue related to a specified build, the data structure is:
{code}
class Issue {
Long ID; // No use, only used in QuickBuild internally
String issueKey;
Long buildId;
String issueType;
String summary;
String status;
String priority;
Date created; // Formated in ISO8601
Date updated;
String resolution;
String assignee;
String reporter;
int modifications; // related modifications
String changeIds; // related change set ids in CSV format
String repositories; // related repository names in CSV format
{code}
h3. Retrieve the builds of an issue
*Before 5.0.14:*
||URI||Response Type||Params||
|$baseURI/builds/\{configuration}/\{issuekey}/|_text/xml_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here, if you want to specify a configuration path, you need add prefix PATH:, for example, _PATH:root/My/DEV_.
* *issuekey* - PATH PARAM
The issue key you want to search.
* *count* - QUERY_PARAM
Specify at most how many records you want. If not specified, all records found will return.|
{code}
http://quickbuild:8810/rest/jira/builds/5/QB-123
{code}
*Since 5.0.14*
||URI||Response Type||Params||
|$baseURI//\{issuekey}/builds/\{configuration}|_text/xml_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here, or specify the configuration path
* *issuekey* - PATH PARAM
The issue key you want to search.
* *count* - QUERY_PARAM
Specify at most how many records you want. If not specified, all records found will return.|
{code}
http://quickbuild:8810/rest/QB-123/jira/builds/5
or
http://quickbuild:8810/rest/QB-123/jira/builds/root/My/DEV
{code}
The response looks like:
{code}
<list>
<build>
<id>321</id>
<version>1.0.15</version>
<status>SUCCESSFUL</status>
<beginDate>2011-06-10T17:11:35.662+08:00</beginDate>
<duration>3409</duration>
<scheduled>false</scheduled>
<requester>Administrator</requester>
<deleted>false</deleted>
</build>
... ...
</list>
{code}
Here, the build element is just a fragment of the build object in QuickBuild, if you need more detailed information about the build, please use [build RESTful API].
h3. Retrieve the changes of an issue
*Before 5.0.14*
||URI||Response Type||Params||
|$baseURI/changes/\{configuration}/\{issuekey}|_text/xml_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here, if you want to specify a configuration path, you need add prefix PATH:, for example, PATH:root/My/DEV
* *key* - PATH_PARAM
The issue key you want to search.
* *count* - QUERY_PARAM
Specify at most how many records you want. If not specified, all records found will return.|
{code}
http://quickbuild:8810/rest/jira/changes/5/TST-123
or
http://quickbuild:8810/rest/jira/changes/PATH:root/My Dev/TST-123
{code}
*Since 5.0.14*
||URI||Response Type||Params||
|$baseURI/\{key}/changes/\{configuration}|_text/xml_|* *configuration* - PATH_PARAM
Specify the configuration. By default, specify configuration id here. You can also specify the configuration path directly
* *key* - PATH_PARAM
The issue key you want to search.
* *count* - QUERY_PARAM
Specify at most how many records you want. If not specified, all records found will return.|
{code}
http://quickbuild:8810/rest/jira/TST-123/changes/5
or
http://quickbuild:8810/rest/jira/TST-123/changes/root/My/DEV
{code}
The response looks like:
{code}
<list>
<changeset>
<user>steve</user>
<date>2011-05-31T03:45:55.000+08:00</date>
<id>f090cd04725c5551f8a439fe0a53591193ea79c3</id>
<repositoryName>hg</repositoryName>
<repositoryType>Mercurial</repositoryType>
<additional>13</additional>
<buildId>321</buildId>
<comment>
add a big file to related to issue TST-23, TST-24 TST-25
</comment>
<modifications>
<modification>
<action>ADD</action>
<path>big.java</path>
<edition>f090cd04725c5551f8a439fe0a53591193ea79c3</edition>
<previousEdition>c11a08aa7525a01e35239b8b6f34d4f8f3bf770b</previousEdition>
<additional>13</additional>
</modification>
</modifications>
</changeset>
... ...
</list>
{code}
h3.