{panel:title=TOC|titleBGColor=#F7D6C1|bgColor=#FFFFFF}
{toc:style=disc|indent=20px}
{panel}
Since QuickBuild 4.0, you can retrieve changes via RESTful APIs. The base URI for changes RESTful APIs is:
{code}
/rest/changes
{code}
h3. List all supported APIs
||URI||Response Type||Params||
|/rest/changes/help|_text/html_| |
h3. Get the data version of changes
||URI||Response Type||Params||
|/rest/changes/version|_text/plain_| |
h3. Get the commit stats
||URI||Response Type||Params||
|/rest/changes/stats/\{configuration}|_text/xml_| * *configuration*
Specify the configuration. By default, specify configuration id here, also, you can specify the configuration path directly
* *build*
Specify the build id you want.
* *from_build*
Specify the from build when finding changes in a build range.
* *to_build*
Specify the to build when finding changes in a build range.
* *from_date*
Specify the from date when finding changes in a build range.
* *to_date*
Specify the to date when finding changes in a build range.
* *date_pattern*
Specify the date pattern when query by a date range, by default, the pattern is yyyyMMdd.
* *repository*
Get the changes only in a specific repository.
* *committer*
Get the changes only committed by a specified committer|
*Query stats of a specific build*
{code}
http://quickbuild:8810/rest/changes/stats/25?build=102
{code}
the response looks like:
{code}
<stats commits="5" modifications="7" added="2" modified="3" deleted="2"/>
{code}
*Query commit stats in a build range*
{code}
http://quickbuild:8810/rest/changes/stats/25?from_build=100&to_build=120
{code}
*Query commit stats in a date range*
{code}
http://quickbuild:8810/rest/changes/stats/25?from_date=20110501&to_date=20110601
{code}
by default, the date pattern is _yyyyMMdd_, you can also specify the date pattern by adding parameter *date_pattern*, the valid date pattern can be found [here|http://download.oracle.com/javase/1.5.0/docs/api/java/text/SimpleDateFormat.html], for example:
{code}
http://quickbuild:8810/rest/changes/stats/25?from_date=2011-05-01&to_date=2011-06-01&date_pattern=yyyy-MM-dd
{code}
*Query commit stats of a specific repository or committer*
By adding _repository_ or _committer_ parameter, you can get the stats of a specific repository or committer, for example:
{code}
http://quickbuild:8810/rest/changes/stats/25?build=102&repository=mysvn
{code}
this will get the stats data for repository mysvn.
h3. Data structure of the changes
In QuickBuild, we use Changeset and Modification to represent a SCM commit. A changeset is an atomic collection of changes to files in a repository and it usually contains several modifications. A modification means developer made a specific action to a file when committed to a repository. In QuickBuild, the actions include:
* ADD
* MODIFY
* DELETE
The action in some SCM, for example, git, mercurial, have more actions, like rename, in QuickBuild, it will be speared into two actions, i.e. DELETE first, and then ADD, and maybe there are also other actions, QuickBuild will use MODIFY action to represent.
Below is the data structure of Changeset:
{code}
Changeset {
String user; // committer
Date date; // commit date
String id; // change id
String comment; // commit comment
String repositoryName; // the repository name defined in QuickBuild
String repositoryType; // the repository type, for example, Subversion, Mercurial, Git
String additional; // the additional information for a commit, for example, revision number for mercurial
Long buildId; // the build this commit belongs to
private List<Modification> modifications;
}
{code}
data structure of Modification:
{code}
Modification {
public enum Action {ADD, DELETE, MODIFY};
public enum PathType {TEXT, BINARY, DIR};
Action action;
String path; // File path
String edition;
String previousEdition;
PathType pathType;
String additional; // Additional information of a modificaiton, for example, revision number for mercurial
}
{code}
h3. Retrieve changesets
||URI||Response Type||Params||
|/rest/changes/\{configuration}|_text/xml_|* *configuration*
Specify the configuration. By default, specify configuration id here, also, you can specify the configuration path directly.
* *build*
Specify the build id you want.
* *from_build*
Specify the from build when finding changes in a build range, must be specified with to_build.
* *to_build*
Specify the to build when finding changes in a build range, must be specified with from_build.
* *date_pattern*
Specify the date pattern when query by a date range, by default, the pattern is yyyyMMdd.
* *from_date*
Specify the from date when finding changes in a build range.
* *to_date*
Specify the to date when finding changes in a build range.
* *repository*
Get the changes only in a specific repository.
* *committer*
Get the changes only committed by the specified committer.
* *offset*
Specify the first record when iterate the records, by default, the offset is 0.
* *limit*
Specify the number of total records you want to retrieve, by default, the limit is 50.
* *asc*
Boolean type, specify the order by commit date ascendent or descendent, by default, it is descendent.|
*Query the changesets of a build*
{code}
http://quickbuild:8810/rest/changes/19?build=102&offset=10&limit=20
{code}
the response looks like:
{code}
<list>
<changeset>
<user>steve</user>
<date>2011-06-03T15:11:40.000+08:00</date>
<id>913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943</id>
<comment>
Fix TST-23: 2-phase load components
</comment>
<repositoryName>hg</repositoryName>
<repositoryType>Mercurial</repositoryType>
<additional>14</additional>
<buildId>321</buildId>
<modifications>
<modification>
<action>MODIFY</action>
<path>Test.java</path>
<edition>913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943</edition>
<previousEdition>f090cd04725c5551f8a439fe0a53591193ea79c3</previousEdition>
<additional>14</additional>
</modification>
<modification>
<action>MODIFY</action>
<path>big.java</path>
<edition>913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943</edition>
<previousEdition>f090cd04725c5551f8a439fe0a53591193ea79c3</previousEdition>
<additional>14</additional>
</modification>
</modifications>
</changeset>
... ...
</list>
{code}
the format of commit date here is using [ISO8601 standard|http://en.wikipedia.org/wiki/ISO_8601]. The _additional_ column stores some extra information of the commits. For mercurial (hg) or bazaar, the _additional_ stores the revision no.
*Query the changesets in a build range*
{code}
http://quickbuild:8810/rest/changes/19?from_build=10&to_build=20
{code}
*Query the changesets in a date range*
{code}
http://quickbuild:8810/rest/changes/19?from_date=20110501&to_date=20110601
{code}
*Query the changesets of a specific repository or committer*
By adding _repository_ or _committer_ parameter, you can get the commits of a specific repository or committer, for example:
{code}
http://quickbuild:8810/rest/changes/root/My/DEV?build=102&repository=mysvn
{code}
here, we use configuration path instead of configuration id.
{note}
if you are using URL directly, you may need escape '/' to %2F (this only applied to QuickBuild 5.0.13 or before), since QuickBuild 5.0.14, you needn't escape the slash '/', just specify the configuration path directly.
{note}
h3. Get build changesets (lively)
Most of the aforementioned APIs are only callable when build finish. Sometimes, you may want to query the changesets during the build is still running, the following APIs are for this purpose:
To query the changesets of this build lively:
{code}
http://quickbuild:8810/rest/changes/commits/build/buildId
{code}
To query the stats of the changesets of this build lively:
{code}
http://quickbuild:8810/rest/changes/stats/build/buildId
{code}
* replace the QuickBuild server host to your own address.
* replace the buildId to the actual build id you want to query.
{toc:style=disc|indent=20px}
{panel}
Since QuickBuild 4.0, you can retrieve changes via RESTful APIs. The base URI for changes RESTful APIs is:
{code}
/rest/changes
{code}
h3. List all supported APIs
||URI||Response Type||Params||
|/rest/changes/help|_text/html_| |
h3. Get the data version of changes
||URI||Response Type||Params||
|/rest/changes/version|_text/plain_| |
h3. Get the commit stats
||URI||Response Type||Params||
|/rest/changes/stats/\{configuration}|_text/xml_| * *configuration*
Specify the configuration. By default, specify configuration id here, also, you can specify the configuration path directly
* *build*
Specify the build id you want.
* *from_build*
Specify the from build when finding changes in a build range.
* *to_build*
Specify the to build when finding changes in a build range.
* *from_date*
Specify the from date when finding changes in a build range.
* *to_date*
Specify the to date when finding changes in a build range.
* *date_pattern*
Specify the date pattern when query by a date range, by default, the pattern is yyyyMMdd.
* *repository*
Get the changes only in a specific repository.
* *committer*
Get the changes only committed by a specified committer|
*Query stats of a specific build*
{code}
http://quickbuild:8810/rest/changes/stats/25?build=102
{code}
the response looks like:
{code}
<stats commits="5" modifications="7" added="2" modified="3" deleted="2"/>
{code}
*Query commit stats in a build range*
{code}
http://quickbuild:8810/rest/changes/stats/25?from_build=100&to_build=120
{code}
*Query commit stats in a date range*
{code}
http://quickbuild:8810/rest/changes/stats/25?from_date=20110501&to_date=20110601
{code}
by default, the date pattern is _yyyyMMdd_, you can also specify the date pattern by adding parameter *date_pattern*, the valid date pattern can be found [here|http://download.oracle.com/javase/1.5.0/docs/api/java/text/SimpleDateFormat.html], for example:
{code}
http://quickbuild:8810/rest/changes/stats/25?from_date=2011-05-01&to_date=2011-06-01&date_pattern=yyyy-MM-dd
{code}
*Query commit stats of a specific repository or committer*
By adding _repository_ or _committer_ parameter, you can get the stats of a specific repository or committer, for example:
{code}
http://quickbuild:8810/rest/changes/stats/25?build=102&repository=mysvn
{code}
this will get the stats data for repository mysvn.
h3. Data structure of the changes
In QuickBuild, we use Changeset and Modification to represent a SCM commit. A changeset is an atomic collection of changes to files in a repository and it usually contains several modifications. A modification means developer made a specific action to a file when committed to a repository. In QuickBuild, the actions include:
* ADD
* MODIFY
* DELETE
The action in some SCM, for example, git, mercurial, have more actions, like rename, in QuickBuild, it will be speared into two actions, i.e. DELETE first, and then ADD, and maybe there are also other actions, QuickBuild will use MODIFY action to represent.
Below is the data structure of Changeset:
{code}
Changeset {
String user; // committer
Date date; // commit date
String id; // change id
String comment; // commit comment
String repositoryName; // the repository name defined in QuickBuild
String repositoryType; // the repository type, for example, Subversion, Mercurial, Git
String additional; // the additional information for a commit, for example, revision number for mercurial
Long buildId; // the build this commit belongs to
private List<Modification> modifications;
}
{code}
data structure of Modification:
{code}
Modification {
public enum Action {ADD, DELETE, MODIFY};
public enum PathType {TEXT, BINARY, DIR};
Action action;
String path; // File path
String edition;
String previousEdition;
PathType pathType;
String additional; // Additional information of a modificaiton, for example, revision number for mercurial
}
{code}
h3. Retrieve changesets
||URI||Response Type||Params||
|/rest/changes/\{configuration}|_text/xml_|* *configuration*
Specify the configuration. By default, specify configuration id here, also, you can specify the configuration path directly.
* *build*
Specify the build id you want.
* *from_build*
Specify the from build when finding changes in a build range, must be specified with to_build.
* *to_build*
Specify the to build when finding changes in a build range, must be specified with from_build.
* *date_pattern*
Specify the date pattern when query by a date range, by default, the pattern is yyyyMMdd.
* *from_date*
Specify the from date when finding changes in a build range.
* *to_date*
Specify the to date when finding changes in a build range.
* *repository*
Get the changes only in a specific repository.
* *committer*
Get the changes only committed by the specified committer.
* *offset*
Specify the first record when iterate the records, by default, the offset is 0.
* *limit*
Specify the number of total records you want to retrieve, by default, the limit is 50.
* *asc*
Boolean type, specify the order by commit date ascendent or descendent, by default, it is descendent.|
*Query the changesets of a build*
{code}
http://quickbuild:8810/rest/changes/19?build=102&offset=10&limit=20
{code}
the response looks like:
{code}
<list>
<changeset>
<user>steve</user>
<date>2011-06-03T15:11:40.000+08:00</date>
<id>913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943</id>
<comment>
Fix TST-23: 2-phase load components
</comment>
<repositoryName>hg</repositoryName>
<repositoryType>Mercurial</repositoryType>
<additional>14</additional>
<buildId>321</buildId>
<modifications>
<modification>
<action>MODIFY</action>
<path>Test.java</path>
<edition>913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943</edition>
<previousEdition>f090cd04725c5551f8a439fe0a53591193ea79c3</previousEdition>
<additional>14</additional>
</modification>
<modification>
<action>MODIFY</action>
<path>big.java</path>
<edition>913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943</edition>
<previousEdition>f090cd04725c5551f8a439fe0a53591193ea79c3</previousEdition>
<additional>14</additional>
</modification>
</modifications>
</changeset>
... ...
</list>
{code}
the format of commit date here is using [ISO8601 standard|http://en.wikipedia.org/wiki/ISO_8601]. The _additional_ column stores some extra information of the commits. For mercurial (hg) or bazaar, the _additional_ stores the revision no.
*Query the changesets in a build range*
{code}
http://quickbuild:8810/rest/changes/19?from_build=10&to_build=20
{code}
*Query the changesets in a date range*
{code}
http://quickbuild:8810/rest/changes/19?from_date=20110501&to_date=20110601
{code}
*Query the changesets of a specific repository or committer*
By adding _repository_ or _committer_ parameter, you can get the commits of a specific repository or committer, for example:
{code}
http://quickbuild:8810/rest/changes/root/My/DEV?build=102&repository=mysvn
{code}
here, we use configuration path instead of configuration id.
{note}
if you are using URL directly, you may need escape '/' to %2F (this only applied to QuickBuild 5.0.13 or before), since QuickBuild 5.0.14, you needn't escape the slash '/', just specify the configuration path directly.
{note}
h3. Get build changesets (lively)
Most of the aforementioned APIs are only callable when build finish. Sometimes, you may want to query the changesets during the build is still running, the following APIs are for this purpose:
To query the changesets of this build lively:
{code}
http://quickbuild:8810/rest/changes/commits/build/buildId
{code}
To query the stats of the changesets of this build lively:
{code}
http://quickbuild:8810/rest/changes/stats/build/buildId
{code}
* replace the QuickBuild server host to your own address.
* replace the buildId to the actual build id you want to query.