<< View previous version | view page history | view next version >>
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_id} | application/xml |
|
Query stats of a specific build
http://quickbuild:8810/rest/changes/stats/25?build_id=102
the response looks like:
<stats commits="5" modifications="7" added="2" modified="3" deleted="2"/>
Query stats for a build range
http://quickbuild:8810/rest/changes/stats/25?from_build=100&to_build=120
Query stats for 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 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_id=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" indexed="true"/> <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_id} | application/xml |
|
Query the changesets of a build
http://quickbuild:8810/rest/changes/commits/19?build_id=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_id=102&repository=mysvn
Retrieve modifications
URI | Response Type | Params |
---|---|---|
/rest/changes/modifications/{configuration_id} | text/xml |
|
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_id=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 later. |
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_id=102&repository=mysvn&change_id=456