Release & Build Deployment
- 21 Jan 2023
- 11 Minutes to read
-
Print
-
DarkLight
-
PDF
Release & Build Deployment
- Updated on 21 Jan 2023
- 11 Minutes to read
-
Print
-
DarkLight
-
PDF
The Release & Build Deployment API offers a simple mechanism for creating releases, creating builds, and deploying builds.
API Usage
All of these endpoints require that an API Key with Release & Build Deployment access is passed into each request. The examples use a query string for simplicity, but you could also use a header, form value, or JSON property. See Using API Keys for more information.
Data Specification
This endpoint receives data entirely as key/value parameters and sends data using the following JSON objects:
Release
| Property | Format |
|---|---|
id |
An integer representing the system-unique identifier of the release. |
releaseNumber |
A string representing the application-unique identifier of the release. |
releaseName |
A string representing the non-unique name or alias for the release. |
sequence |
An integer representing the sequence relative to other releases in the application. |
template |
A string of the template name used for this release, or null if no template is used. |
status |
A string consisting of active, deployed, or canceled. |
createdBy |
A string representing the user who created the release, or SYSTEM if created non-interactively. |
createdOn |
A string representing the UTC date when the release was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
canceledBy |
A string representing the user who canceled the release, or SYSTEM if created non-interactively. |
canceledOn |
A string representing the UTC date when the release was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
targetDate |
A string representing the UTC date of the target release date in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
applicationId |
An integer representing the system-unique identifier of the application for the release. |
applicationName |
A string representing the system-unique name of the application for the release. |
pipelineName |
A string representing the name of the pipeline used by the release. |
furthestBuildId |
An integer representing the system-unique identifier of the active or deployed build that has made it furthest in the pipeline for the release. |
furthestBuildNumber |
A string representing the application-unique number of the active or deployed build that has made it furthest in the pipeline for the release. |
latestBuildId |
An integer representing the system-unique identifier of the active or deployed build that was most recently created. |
latestBuildNumber |
A string representing the application-unique number of the active or deployed build that was most recently created. |
Build
| Property | Format |
|---|---|
id |
An integer representing the system-unique identifier of the build. |
buildNumber |
A string representing the release-unique identifier of the build. |
status |
A string consisting of active, deployed, or rejected. |
createdBy |
A string representing the user who created the build, or SYSTEM if created non-interactively. |
createdOn |
A string representing the UTC date when the build was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
rejectedBy |
A string representing the user who rejected the build, or SYSTEM if rejected non-interactively. |
rejectedOn |
A string representing the UTC date when the build was rejected, in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
pipelineName |
A string representing the name of the pipeline used by the build. |
furthestStage |
A string representing the name the furthest stage the build has advanced to in the pipeline. |
applicationId |
An integer representing the system-unique identifier of the application for the build. |
applicationName |
A string representing the system-unique name of the application for the build. |
releaseId |
An integer representing the system-unique identifier of the release for the build. |
releaseNumber |
A string representing the application-unique number of the release for the build. |
releaseName |
A string representing the name of the release for the build. |
Deployment
| Property | Format |
|---|---|
id |
An integer representing the system-unique identifier of the deployment. |
plan |
A string representing the name of the plan used for deployment. |
status |
A string consisting of pending, executing, succeeded, warned, or failed. |
started |
A string representing the UTC date when the deployment actually started, in ISO 8601 format (yyyy-MM-ddThh:mm:ss), or null if the execution hasn't started. |
ended |
A string representing the UTC date when the deployment completed, in ISO 8601 format (yyyy-MM-ddThh:mm:ss), or null if the execution hasn't completed. |
createdBy |
A string representing the user who initiated the deployment, or SYSTEM if initiated non-interactively. |
createdOn |
A string representing the UTC date when the deployment was initiated, in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
canceledBy |
A string representing the user who canceled the deployment (SYSTEM if canceled non-interactively), or null if the deployment was not canceled. |
canceledOn |
A string representing the UTC date when the deployment was canceled, in ISO 8601 format (yyyy-MM-ddThh:mm:ss), or null if the deployment was not canceled. |
pipelineName |
A string representing the name of the pipeline used by the deployment. |
pipelineStageName |
A string representing the name the stage in the pipeline used by the deployment. |
environmentId |
An integer representing the system-unique identifier of the environment used by the deployment, or null if no environment is in context. |
environmentName |
A string representing the name of the environment used by the deployment, or null if no environment is in context. |
applicationId |
An integer representing the system-unique identifier of the application for the deployment. |
applicationName |
A string representing the system-unique name of the application for the deployment. |
releaseId |
An integer representing the system-unique identifier of the release for the deployment. |
releaseNumber |
A string representing the application-unique number of the release for the deployment. |
releaseName |
A string representing the name of the release for the deployment. |
buildId |
An integer representing the system-unique identifier of the build for the deployment. |
buildNumber |
A string representing the release-unique number of the build for the deployment. |
In BuildMaster 6.1 and earlier, these data objects contained a pipelineId which was an integer identifier for the pipeline used by the release. However, since BuildMaster 6.2, pipelines are stored in raft repositories (which can be a zip file or a git repository) and therefore no longer have a native identifier.
Endpoint Specifications
This endpoint receives data entirely as key/value parameters, which may be specified in both the querystring and body (application/x-www-form-urlencoded); duplicate keys will result in an failed request (400 status).
Get Releases
GET or POST /api/releases
Returns a status of 200 and a body with an array of release objects based on the specified optional filter parameters:
| Filter | Parameter Specification |
|---|---|
| Application | Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Release | Either a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value. |
| Pipeline | A key named pipelineName with any value. |
| Status | A key named status with a value of active, canceled, or deployed. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Create Release
POST or PUT /api/releases/create
Returns a status of 200 and a body with a release object that was created with the following input parameters:
| Input | Parameter Specification |
|---|---|
| Application | Required. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Release Number | Required. A key named releaseNumber with any value. |
| Pipeline | Required. A key named pipelineName with any value. |
| Release Name | Optional. A key named releaseName with any value. |
| Variables | Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Create Release from Template
POST or PUT /api/releases/create-from-template
Returns a status of 200 and a body with a release object that was created with the following input parameters:
| Input | Parameter Specification |
|---|---|
| Application | Required. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Release Number | Required. A key named releaseNumber with any value. |
| Template | Required. A key named template with any value. |
| Release Name | Optional. A key named releaseName with any value. |
| Pipeline Name | Optional. Available in BuildMaster 7.0.22+, a key named pipelineName with the name of a valid pipeline. When set, this overrides the value in the Template. |
| Variables | Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Cancel Release
POST or PUT /api/releases/cancel
Returns a status of 200 if the release was canceled:
| Input | Parameter Specification |
|---|---|
| Release | Required. Either a key named releaseId with an integer value, or a key named releaseNumber with any value. |
| Application | Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Reason | Optional. A key named reason with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Restore Release
POST or PUT /api/releases/restore
Returns a status of 200 if the release was restored:
| Input | Parameter Specification |
|---|---|
| Release | Required. Either a key named releaseId with an integer value, or a key named releaseNumber with any value. |
| Application | Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Get Builds
GET or POST /api/releases/builds
Returns a status of 200 and a body with an array of build objects based on the specified optional filter parameters:
| Filter | Parameter Specification |
|---|---|
| Application | Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Release | Either a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value. |
| Build | Either a key named buildId with an integer value, or a key named buildNumber with any value. |
| Pipeline | A key named pipelineName with any value. |
| Stage | A key named furthestStage with any value. |
| Status | A key named status with a value of active, rejected, or deployed. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Create Build
POST or PUT /api/releases/builds/create
Returns a status of 200 and a body with a build object that was created with the following input parameters:
| Input | Parameter Specification |
|---|---|
| Release | Required. Either a key named releaseId with an integer value, or a key named releaseNumber with any value. |
| Application | Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Build Number | Optional. A key named buildNumber with any value; if not specified, the build number will be automatically generated. |
| Variables | Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Get Deployments
GET or POST /api/releases/builds/deployments
Returns a status of 200 and a body with an array of deployment objects based on the specified optional filter parameters:
| Filter | Parameter Specification |
|---|---|
| Application | Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Release | Either a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value. |
| Build | Either a key named buildId with an integer value, or a key named buildNumber with any value. |
| Deployment | A key named deploymentId with an integer value. |
| Pipeline | A key named pipelineName with any value. |
| Stage | A key named pipelineStageName with any value. |
| Environment | Either a key named environmentId with an integer value, or a key named environmentName with any value. |
| Status | A key named status with a value of pending, executing, succeeded, warned, or failed. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Deploy Build
POST or PUT /api/releases/builds/deploy
Returns a status of 200 and a body with an array of deployment objects that were created with the following input parameters:
| Input | Parameter Specification |
|---|---|
| Build | Required. Either a key named buildId with an integer value, or a key named buildNumber with any value. |
| Release | Required if buildNumber is specified, otherwise must not be set. Either a key named releaseId with an integer value, or a key named releaseNumber with any value. |
| Application | Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| To Stage | Optional. A key named toStage with any value. If not supplied, the next stage in the pipeline will be used. |
| Force | Optional. A key named force with a value of true or false. |
| Start Time | Optional. A key named startTime with a timestamp of when the deployment should start. If not supplied, the deployment will start immediately. If the timestamp does not contain a date, it defaults to today. If a date is specified without a time, it defaults to midnight. If there is no time zone specified, it defaults to the server's local time zone. Available in BuildMaster 6.0.2+ |
| Variables | Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Reject Build
POST or DELETE /api/releases/builds/reject
Returns a status of 200 if the build was rejected:
| Input | Parameter Specification |
|---|---|
| Build | Required. Either a key named buildId with an integer value, or a key named buildNumber with any value. |
| Release | Required if buildNumber is specified, otherwise must not be set. Either a key named releaseId with an integer value, or a key named releaseNumber with any value. |
| Application | Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value or a key named applicationName with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Was this article helpful?
