Release & Build Deployment
  • 21 Jan 2023
  • 11 Minutes to read
  • Dark
    Light
  • PDF

Release & Build Deployment

  • Dark
    Light
  • 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?