changes.
| h1. Access build by build id |
| |
| h2. Syntax |
| Build can be accessed by id using http GET method through below url: |
| {code}http://localhost:8810/rest/builds/<build 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 build with id _14_: |
| {code}curl -u admin:admin http://localhost:8810/rest/builds/14{code} |
| |
| h1. Access build status by build id |
| |
| h2. Syntax |
| Build status can be accessed by build id using http GET method through below url: |
| {code}http://localhost:8810/rest/builds/<build id>/status{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 status of build with id _14_: |
| {code}curl -u admin:admin http://localhost:8810/rest/builds/14/status{code} |
| |
| h1. Access build begin date by build id |
| |
| h2. Syntax |
| Build begin date can be accessed by build id using http GET method through below url: |
| {code}http://localhost:8810/rest/builds/<build id>/begin_date{code} |
| The response is of mime type _text/plain_, and the content is string representation of build begin date (mill-seconds since January 1, 1970, 00:00:00 GMT) |
| |
| 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 begin date of build with id _14_: |
| {code}curl -u admin:admin http://localhost:8810/rest/builds/14/begin_date{code} |
| |
| h1. Access build version by build id |
| |
| h2. Syntax |
| Build version can be accessed by build id using http GET method through below url: |
| {code}http://localhost:8810/rest/builds/<build id>/version{code} |
| The response is of mime type _text/plain_, and the content is string representation of the build version. |
| |
| 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 version of build with id _14_: |
| {code}curl -u admin:admin http://localhost:8810/rest/builds/14/version{code} |
| |
| h1. Access build duration by build id |
| |
| h2. Syntax |
| Build duration can be accessed by build id using http GET method through below url: |
| {code}http://localhost:8810/rest/builds/<build id>/duration{code} |
| The response is of mime type _text/plain_, and the content is string representation of the build duration (milli-seconds). Status 204 (No Content) will be returned if build is not finished. |
| |
| 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 duration of build with id _14_: |
| {code}curl -u admin:admin http://localhost:8810/rest/builds/14/duration{code} |
| |
| {anchor:get request id} |
| h1. Get build request id by build id |
| |
| h2. Syntax |
| [Build request|Interact with Build Requests] id can be accessed by build id using http GET method through below url: |
| {code}http://localhost:8810/rest/builds/<build id>/request_id{code} |
| The response is of mime type _text/plain_, and the content is string representation of the build request id. Status 204 (No Content) will be returned if build is finished. |
| |
| 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 get request id of build with id _14_: |
| {code}curl -u admin:admin http://localhost:8810/rest/builds/14/request_id{code} |
| |
| h1. Access executed steps by build id |
| |
| h2. Syntax |
| Executed steps of a build can be accessed by build id using http GET method through below url: |
| {code}http://localhost:8810/rest/builds/<build id>/steps{code} |
| The response is of mime type _application/xml_, and the content is XML representation of the list of steps executed in the build. |
| |
| 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 settings of belonging configuration. |
| |
| h2. Demo |
| Below [curl|http://curl.haxx.se/] command demostrates how to access executed steps by build with id _14_: |
| {code}curl -u admin:admin http://localhost:8810/rest/builds/14/steps{code} |
| |
| h1. Access used repositories by build id |
| |
| h2. Syntax |
| Used repositories of a build can be accessed by build id using http GET method through below url: |
| {code}http://localhost:8810/rest/builds/<build id>/repositories{code} |
| The response is of mime type _application/xml_, and the content is XML representation of the list of repositories used in the build. |
| |
| 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 settings of belonging configuration. |
| |
| h2. Demo |
| Below [curl|http://curl.haxx.se/] command demostrates how to access used repositories by build with id _14_: |
| {code}curl -u admin:admin http://localhost:8810/rest/builds/14/repositories{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_, _TIMEOUT_. If left empty, any build status will be matched.| |
| | |status|Status of the build to match. Valid build statuses are: _SUCCESSFUL_, _FAILED_, _RECOMMENDED_, _CANCELLED_, _RUNNING_, _TIMEOUT_. 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.| |
| |first|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.| |
| |
| The response is of mime type _application/xml_, and the content is XML representation of list of matched builds. If no any search criterias are 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. 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} |
| 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 authorized QuickBuild user if the anonymous does not have _SAVE_BUILD_ permission on the belonging configuration. |
| |
| 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/builds/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 http://localhost:8810/rest/builds{code} |
| |
| {warning}Moving builds to other configurations is not suggested since it will result in inaccurate change sets when compare builds in the original configuration.{warning} |
| |
| h1. Create build |
| |
| h2. Syntax |
| Build object can be created by posting XML representation of the build to below url: |
| {code}http://localhost:8810/rest/build{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. |
| |
| {note} This is different from [requesting new build|Interact with Build Requests#request new build] in the system. It simply adds a build object in the system, and is normally used to move build objects between different servers or configurations.{note} |
| |
| 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/builds/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 http://localhost:8810/rest/builds{code} |
| |
| h1. Delete Build |
| |
| h2. Syntax |
| Build can be deleted using http DELETE method through below url: |
| {code}http://localhost:8810/rest/builds/<build id>{code} |
| |
| {note}This service simply deletes the build object in database, and is different from build cacellation. You may follow below steps to cancel a running build: |
| # [Get build request id|#get request id] |
| # [Delete the build request|interact with build requests#delete build request] with build request id if it is not empty |
| {note} |
| |
| h2. Security |
| You will need to use http BASIC authentication to login as authorized QuickBuild user 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/builds/100{code} |