Interact with Changes

Added by Steve Luo, edited by Steve Luo on Jun 13, 2011
You are viewing an old version (v. 25) of this page.
The latest version is v. 27, last edited on Jun 13, 2011 (view differences | )
<< View previous version | view page history | view next version >>
TOC

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, if you want to specify a configuration path, you need add prefix PATH:, for example, PATH:root/My/DEV
  • 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 the 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 are meta data for changeset and modification:

<meta name="changesets">
  <column name="buildId" dataType="ID" isKey="true" />
  <column name="changeId" dataType="STRING" isKey="true"/>
  <column name="repository" dataType="STRING" isKey="true"/>
  <column name="commitDate" dataType="TIME"/>
  <column name="comment" dataType="BLOB"/>
  <column name="additional" dataType="BLOB"/>
  <column name="modifications" dataType="INTEGER"/>
  <column name="committer" dataType="STRING" /> <!-- Committer of the changeset -->
  <column name="userId" dataType="ID" />  <!-- QuickBuild user id, only valid when committer is also a valid quickbuild user -->
  <column name="added" dataType="INTEGER"/> <!-- Count of ADD action -->
  <column name="modified" dataType="INTEGER"/> <!-- Count of MODIFY action -->
  <column name="deleted" dataType="INTEGER"/> <!-- Count of DELETE action -->
</meta>
<meta name="modifications">
  <column name="buildId" dataType="ID" isKey="true"/>
  <column name="changeId" dataType="STRING" isKey="true"/>
  <column name="repository" dataType="STRING" isKey="true"/>
  <column name="fileName" dataType="STRING" isKey="true"/>
  <column name="edition" dataType="STRING" />
  <column name="previousEdition" dataType="STRING" />
  <column name="action" dataType="ENUM" values="ADD,MODIFY,DELETE" indexed="TRUE"/>
  <column name="pathType" dataType="ENUM" values="TEXT, BINARY, DIR"/>
</meta>

Changeset is related with modifications by below columns: buildId, changeId and repository. With those columns, you can search modifications for a specific changeset.

Retrieve changesets

URI Response Type Params
/rest/changes/changesets/{configuration} text/xml
  • configuration
    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
  • 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 false.

Query the changesets of a build

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

the response looks like:

<report name="changesets" version="0.0" locale="en_US">
  <row ID="10" buildId="320" changeId="f090cd04725c5551f8a439fe0a53591193ea79c3" repository="hg" commitDate="2011-05-31T03:45:55.000+08:00" modifications="1" committer="steve" userId="2" added="1" modified="0" deleted="0">
    <comment><![CDATA[some comments]]></comment>
    <additional><![CDATA[ 13 ]]></additional>
  </row>
  <row ID="11" buildId="320" changeId="f090cd04725c5551f8a439fe0a53591193ea79c3" repository="hg" commitDate="2011-05-31T03:45:55.000+08:00" modifications="1" committer="steve" userId="2" added="1" modified="0" deleted="0">
    <comment><![CDATA[some comments]]></comment>
    <additional><![CDATA[ 13 ]]></additional>
  </row>
	
	... ...
</report>

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/commits/19?from_build=10&to_build=20

Query the changesets in a date range

http://quickbuild:8810/rest/changes/commits/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/commits/25?build=102&repository=mysvn

Retrieve modifications

URI Response Type Params
/rest/changes/modifications/{configuration} text/xml
  • configuration
    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
  • 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.
  • change_id
    Specify the change id you want to find.
  • 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 false.

Query modifications of a build
Below example shows how to get the modifications for a specific build.

http://quickbuild:8810/rest/changes/modifications/10?build=120&offset=0&limit=20

the response looks like:

<report name="modifications" version="0.0" locale="en_US">
  <row ID="1" buildId="321" changeId="913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943" repository="hg" fileName="Test.java" edition="913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943" previousEdition="f090cd04725c5551f8a439fe0a53591193ea79c3" action="MODIFY" commitDate="2011-06-03T15:11:40.000+08:00" committer="steve" userId="2">
    <comment><![CDATA[Fix TST-23: 2-phase load components 
Fix TST-24: How are you?]]></comment>
    <additional><![CDATA[ 14 ]]></additional>
  </row>

  ... ...

</report>

The columns: commitDate, committer, userId, comment which are columns in changesets are also included in the response so you may fetch the modifications directly instead of fetching changesets first and searching the modifications then.

Query modifications in a build range

http://quickbuild:8810/rest/changes/modifications/10?from_build=100&to_build=200

Query modifications in a date range

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

Query the modifications of a specific repository, change id or committer
By adding repository or committer parameter, you can get the modifications of a specific repository or committer, for example, to search the modifications for change id 456, you can use below URL:

http://quickbuild:8810/rest/changes/modifications/25?build=102&repository=mysvn&change_id=456
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.