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