changes.
| {anchor:psuedo id} |
| h1. Build psuedo id |
| To facilitate the interaction with builds, the build psuedo id is used. A build psuedo id is of below formats: |
| ||format||meaning|| |
| |<build id>|A certain build id, for example: _100_| |
| |<configuration id>.latest|Latest build of specified configuration, for example: _2.latest_| |
| |<configuration id>.latest_finished|Latest finished build of specified configuration, for example: _2.latest_finished_| |
| |<configuration id>.latest_successful|Latest successful build of specified configuration, for example: _2.latest_successful_| |
| |<configuration id>.latest_recommended|Latest recommended build of specified configuration, for example: _2.latest_recommended_| |
| |<configuration id>.latest_failed|Latest failed build of specified configuration, for example: _2.latest_failed_| |
| |
| h1. Access build by psuedo id |
| |
| h2. Syntax |
| Build can be accessed by build psuedo id using http GET method through below url: |
| {code}http://localhost:8810/rest/build?id=<build psuedo id>{code} |
| The response is of mime type _application/xml_, and the content is xml representation of the build. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous does not have permission to access belonging configuration of requested build. |
| |
| h2. Demo |
| Below [curl|http://curl.haxx.se/] command demostrates how to access xml representation of the latest build of the configuration with id _2_: |
| {code}curl -u admin:admin http://localhost:8810/rest/build?id=2.latest{code} |
| |
| h1. Access build by configuration id and build version |
| |
| h2. Syntax |
| Build can be accessed by configuration id and build version using http GET method through below url: |
| {code}http://localhost:8810/rest/build?configuration_id=<configuration id>&version=<build version>{code} |
| The response is of mime type _application/xml_, and the content is xml representation of the build. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous does not have permission to access belonging configuration of requested build. |
| |
| h2. Demo |
| Below [curl|http://curl.haxx.se/] command demostrates how to access xml representation of build _1.0.6_ in configuration with id _2_: |
| {code}curl -u admin:admin "http://localhost:8810/rest/build?configuration_id=2&version=1.0.6"{code} |
| |
| h1. Access build status by psuedo id |
| |
| h2. Syntax |
| Build status can be accessed by build psuedo id using http GET method through below url: |
| {code}http://localhost:8810/rest/build/status?id=<build psuedo id>{code} |
| The response is of mime type _text/plain_, and the content is string representation of the build status. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous does not have permission to access belonging configuration of requested build. |
| |
| h2. Demo |
| Below [curl|http://curl.haxx.se/] command demostrates how to access build status of latest build in configuration with id _2_: |
| {code}curl -u admin:admin http://localhost:8810/rest/build/status?id=2.latest{code} |
| |
| h1. Access build id by psuedo id |
| |
| h2. Syntax |
| Build id can be accessed by build psuedo id using http GET method through below url: |
| {code}http://localhost:8810/rest/build/id?id=<build psuedo id>{code} |
| The response is of mime type _text/plain_, and the content is string representation of the build id. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous does not have permission to access belonging configuration of requested build. |
| |
| h2. Demo |
| Below [curl|http://curl.haxx.se/] command demostrates how to access build id of latest build in configuration with id _2_: |
| {code}curl -u admin:admin http://localhost:8810/rest/build/id?id=2.latest{code} |
| |
| h1. Access executed steps by build psuedo id |
| |
| h2. Syntax |
| Executed steps of a build can be accessed by psuedo id using http GET method through below url: |
| {code}http://localhost:8810/rest/build/steps?id=<build psuedo id>{code} |
| The response is of mime type _application/xml_, and the content is the list of steps executed in the build. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as QuickBuild administrator if the anonymous does not have administrative permission. |
| |
| h2. Demo |
| Below [curl|http://curl.haxx.se/] command demostrates how to access executed steps by latest build in configuration with id _2_: |
| {code}curl -u admin:admin http://localhost:8810/rest/build/steps?id=2.latest{code} |
| |
| h1. Access used repositories by build psuedo id |
| |
| h2. Syntax |
| Used repositories of a build can be accessed by psuedo id using http GET method through below url: |
| {code}http://localhost:8810/rest/build/repositories?id=<build psuedo id>{code} |
| The response is of mime type _application/xml_, and the content is the list of repositories used in the build. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as QuickBuild administrator if the anonymous does not have administrative permission. |
| |
| h2. Demo |
| Below [curl|http://curl.haxx.se/] command demostrates how to access used repositories by latest build in configuration with id _2_: |
| {code}curl -u admin:admin http://localhost:8810/rest/build/repositories?id=2.latest{code} |
| |
| h1. Search builds |
| |
| h2. Syntax |
| Builds can be searched using http GET method through below url: |
| {code}http://localhost:8810/rest/builds?<search criteria1>=<value1>&<search criteria2>=<value2>&...{code} |
| Query string part of the url represents various search criterias to restrict the search result. Supported search criterias are: |
| ||Search criteria||Explanation|| |
| |configuration_id|This tells QuickBuild under which configuration id to search builds. If not specified, all configurations will be searched.| |
| |recursive|If set to _true_, QuickBuild will also search builds in all descendent configurations of specified configuration. The value is assumed as _false_ if not specified.| |
| |from_date|In the format of _yyyy-MM-dd_, for example: _2009-11-12_. If specified, search builds generated after this date| |
| |to_date|In the format of _yyyy-MM-dd_, for example: _2009-11-12_. If specified, search builds generated before this date| |
| |version|Specify the build version to match. The character _*_ can be used in the version string to do wildcard match. If not specified, all versions will be matched.| |
| |status|Status of the build to match. Valid build statuses are: _SUCCESSFUL_, _FAILED_, _RECOMMENDED_, _CANCELLED_, _RUNNING_, _WAITING_. If left empty, any build status will be matched.| |
| |user_id|Match builds which is triggered by specified user. If not specified, builds triggered by any user will be matched.| |
| |index|Specify start position of search results. Position _0_ is assumed if this param is not specified.| |
| |count|Specify number of builds to return. All matching builds will be returned if this param is not specified.| |
| If no any search criterias specified, all builds in the system will be returned. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have permission to access returned builds. |
| |
| h2. Demo |
| Below [curl|http://curl.haxx.se/] commands demonstrates how to combine different criterias to perform search: |
| # Search all failed builds under configuration with id _2_: |
| {code}curl -u admin:admin "http://localhost:8810/rest/builds?configuration_id=2&status=FAILED"{code} |
| # Search all successful builds generated before _2009-11-12_ in the system: |
| {code}curl -u admin:admin "http://localhost:8810/rest/builds?status=SUCCESSFUL&to_date=2009-11-12"{code} |
| # Search all failed builds with version containing _qa_: |
| {code}curl -u admin:admin "http://localhost:8810/rest/builds?version=*qa*&status=FAILED"{code} |
| |
| h1. Trigger build |
| |
| h2. Syntax |
| Build can be triggered by posting the triggering parameter xml to below url: |
| {code}http://localhost:8810/rest/trigger{code} |
| A sample triggering parameter xml is like below: |
| {code} |
| <com.pmease.quickbuild.rest.TriggerParams> |
| <!-- This element tells QuickBuild in what configuration to trigger build. --> |
| <configurationId>2</configurationId> |
| |
| <!-- This element tells whether or not to respect build condition of the configuration. |
| If this is set to true, and if the build condition evaluates to false, build will |
| not be triggered. --> |
| <respectBuildCondition>false</respectBuildCondition> |
| |
| <!-- This element is optional and used to specify variables for build triggering. If |
| specified, it will override the variable with the same name defined in configuration |
| basic setting. --> |
| <variables> |
| <entry> |
| <string>name1</string> |
| <string>value1</string> |
| </entry> |
| <entry> |
| <string>name2</string> |
| <string>value2</string> |
| </entry> |
| </variables> |
| |
| <!-- This element tells QuickBuild whether or not to wait for finishing of the build. --> |
| <waitForFinish>false</waitForFinish> |
| </com.pmease.quickbuild.rest.TriggerParams> |
| {code} |
| |
| The response is of mime type _text/plain_ and the content is string representation of newly generated build id. If the element _respectBuildCondition_ is set to _true_, and if the build condition evaluates to _false_, id of latest build of specified configuration will be returned instead. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have _RUN_BUILD_ permission for the requested configuration. |
| |
| h2. Demo |
| We use [curl|http://curl.haxx.se/] to demonstrate how to trigger a build in configuration with id _2_: |
| # Save the sample triggering param xml described above to file _tempfile.xml_. |
| # Post content of _tempfile.xml_ to QuickBuild using below command: |
| {code}curl -X POST -u admin:admin -d @tempfile.xml http://localhost:8810/rest/trigger{code} |
| |
| h1. Promote build |
| |
| h2. Syntax |
| Build can be promoted by posting the promotion parameter xml to below url: |
| {code}http://localhost:8810/rest/promote{code} |
| A sample promotion parameter xml is like below: |
| {code} |
| <com.pmease.quickbuild.rest.PromoteParams> |
| <!-- This element represents the destination configuration of the promotion process. --> |
| <configurationId>5</configurationId> |
| |
| <!-- This element defines the promotion source, including id of the build to be promoted, |
| and the files to be promoted. The _files_ element is optional. --> |
| <promotionSource> |
| <buildId>100</buildId> |
| <files> |
| <com.pmease.quickbuild.rest.RetrieveFiles> |
| <srcPath>artifacts</srcPath> |
| <patterns>**</patterns> |
| </com.pmease.quickbuild.rest.RetrieveFiles> |
| </files> |
| </promotionSource> |
| |
| <!-- This element is optional and can be used to specify variables for the promotion |
| process. --> |
| <variables> |
| <entry> |
| <string>name1</string> |
| <string>value1</string> |
| </entry> |
| <entry> |
| <string>name2</string> |
| <string>value2</string> |
| </entry> |
| </variables> |
| </com.pmease.quickbuild.rest.PromoteParams> |
| {code} |
| |
| The response is of mime type _text/plain_ and the content is string representation of newly generated build id as result of the promotion. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have _PROMOTE_BUILD_ permission for the destination configuration. |
| |
| h2. Demo |
| We use [curl|http://curl.haxx.se/] to demonstrate how to promote all artifacts of build with id _100_ to configuration with id _2_: |
| # Save the sample promotion param xml described above to file _tempfile.xml_. |
| # Post content of _tempfile.xml_ to QuickBuild using below command: |
| {code}curl -X POST -u admin:admin -d @tempfile.xml http://localhost:8810/rest/promote{code} |
| |
| h1. Update build |
| |
| h2. Syntax |
| Build can be updated by posting xml representation of the build to below url: |
| | {code}http://localhost:8810/rest/build{code} |
| | {code}http://localhost:8810/rest/builds{code} |
| Please note that the _configuration_ element denotes id of the belonging configuration. |
| Normally you do not need to create the xml from scratch: you may retrieve xml representation of the build using the http GET method, modify certain parts of the xml and post back to above url. |
| The response is of mime type _text/plain_ and the content is string representation of the build id being updated. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as administrator if the anonymous does not have administrative rights. |
| |
| h2. Demo |
| We will use [curl|http://curl.haxx.se/] to demonstrate how to move the build to be under another configuration. Let's assume the build id is _100_, and the destination configuration id is _6_. |
| # Retrieve xml representation of desired build into a temp file using below command: |
| {code}curl -u admin:admin http://localhost:8810/rest/build?id=100 > tempfile.xml{code} |
| # Edit _tempfile.xml_ and change the _configuration_ property to take the value _6_. |
| # Post back modified content using below command: |
| {code}curl -X POST -u admin:admin -d @tempfile.xml -u admin:admin http://localhost:8810/rest/build{code} |
| |
| h1. Create build |
| |
| h2. Syntax |
| Build can be created by posting xml representation of the build to below url: |
| | {code}http://localhost:8810/rest/build{code} |
| | {code}http://localhost:8810/rest/builds{code} |
| Please note that: |
| # The posted xml should NOT contain the _id_ element; otherwise, QuickBuild will treat the post as an updating to the build with that id. |
| # The _configuration_ element denotes id of the belonging configuration. |
| Normally you do not need to create the xml from scratch: you may retrieve xml representation of a templating build using the http GET method, remove the _id_ element, modify certain parts and post back to above url. |
| The response is of mime type _text/plain_ and the content is string representation of id of the newly created build. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as administrator if the anonymous does not have administrative rights. |
| |
| h2. Demo |
| We will use [curl|http://curl.haxx.se/] to demonstrate how to create a new build by copying an existing build with id _100_. |
| # Retrieve xml representation of build with id _100_ into a temp file using below command: |
| {code}curl -u admin:admin http://localhost:8810/rest/build?id=100 > tempfile.xml{code} |
| # Edit _tempfile.xml_ to remove the _id_ element, and change other properties as desired. |
| # Post back modified content using below command: |
| {code}curl -X POST -u admin:admin -d @tempfile.xml -u admin:admin http://localhost:8810/rest/build{code} |
| |
| h1. Cancel build |
| |
| h2. Syntax |
| Build can be cancelled using http GET method through below url: |
| {code}http://localhost:8810/rest/cancel?id=<build id>{code} |
| Here _<build id}_ stands for id of the build to be cancelled. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as authenticated QuickBuild user if the anonymous does not have _STOP_BUILD_ permission on the belonging configuration. |
| |
| h2. Demo |
| Below [curl|http://curl.haxx.se/] command demonstrates how to cancel the build with id _100_: |
| {code}curl -X DELETE -u admin:admin http://localhost:8810/rest/canceld?id=100{code} |
| |
| h1. Delete build |
| |
| h2. Syntax |
| Build can be deleted using http DELETE method through below url: |
| {code}http://localhost:8810/rest/build?id=<build id>{code} |
| Here _<build id}_ stands for id of the build to be deleted. |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as administrator if the anonymous does not have _DELETE_BUILD_ permission on the belonging configuration. |
| |
| h2. Demo |
| Below [curl|http://curl.haxx.se/] command demonstrates how to delete the build with id _100_: |
| {code}curl -X DELETE -u admin:admin http://localhost:8810/rest/build?id=100{code} |