Interact with Changes

TOC

List all supported APIs
Get the data version of changes
Get the commit stats
Data structure of the changes
Retrieve changesets
Get build changesets (lively)

Since QuickBuild 4.0, you can retrieve changes via RESTful APIs. The base URI for changes RESTful APIs is:

/rest/changes

List all supported APIs

URI	Response Type	Params
/rest/changes/help	text/html

Get the data version of changes

URI	Response Type	Params
/rest/changes/version	text/plain

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

http://quickbuild:8810/rest/changes/stats/25?build=102

the response looks like:

<stats commits="5" modifications="7" added="2" modified="3" deleted="2"/>

Query commit stats in a build range

http://quickbuild:8810/rest/changes/stats/25?from_build=100&to_build=120

Query commit stats in a date range

http://quickbuild:8810/rest/changes/stats/25?from_date=20110501&to_date=20110601

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, for example:

http://quickbuild:8810/rest/changes/stats/25?from_date=2011-05-01&to_date=2011-06-01&date_pattern=yyyy-MM-dd

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:

http://quickbuild:8810/rest/changes/stats/25?build=102&repository=mysvn

this will get the stats data for repository mysvn.

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:

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;
}

data structure of Modification:

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
}

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

http://quickbuild:8810/rest/changes/19?build=102&offset=10&limit=20

the response looks like:

<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>

the format of commit date here is using ISO8601 standard. 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

http://quickbuild:8810/rest/changes/19?from_build=10&to_build=20

Query the changesets in a date range

http://quickbuild:8810/rest/changes/19?from_date=20110501&to_date=20110601

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:

http://quickbuild:8810/rest/changes/root/My/DEV?build=102&repository=mysvn

here, we use configuration path instead of configuration id.

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.

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:

http://quickbuild:8810/rest/changes/commits/build/buildId

To query the stats of the changesets of this build lively:

http://quickbuild:8810/rest/changes/stats/build/buildId

replace the QuickBuild server host to your own address.
replace the buildId to the actual build id you want to query.