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

Release & Build Deployment

  • Dark
    Light
  • PDF

Article Summary

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

PropertyFormat
idAn integer representing the system-unique identifier of the release.
releaseNumberA string representing the application-unique identifier of the release.
releaseNameA string representing the non-unique name or alias for the release.
sequenceAn integer representing the sequence relative to other releases in the application.
templateA string of the template name used for this release, or null if no template is used.
statusA string consisting of active, deployed, or canceled.
createdByA string representing the user who created the release, or SYSTEM if created non-interactively.
createdOnA string representing the UTC date when the release was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss).
canceledByA string representing the user who canceled the release, or SYSTEM if created non-interactively.
canceledOnA string representing the UTC date when the release was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss).
targetDateA string representing the UTC date of the target release date in ISO 8601 format (yyyy-MM-ddThh:mm:ss).
applicationIdAn integer representing the system-unique identifier of the application for the release.
applicationNameA string representing the system-unique name of the application for the release.
pipelineNameA string representing the name of the pipeline used by the release.
furthestBuildIdAn integer representing the system-unique identifier of the active or deployed build that has made it furthest in the pipeline for the release.
furthestBuildNumberA string representing the application-unique number of the active or deployed build that has made it furthest in the pipeline for the release.
latestBuildIdAn integer representing the system-unique identifier of the active or deployed build that was most recently created.
latestBuildNumberA string representing the application-unique number of the active or deployed build that was most recently created.

Build

PropertyFormat
idAn integer representing the system-unique identifier of the build.
buildNumberA string representing the release-unique identifier of the build.
statusA string consisting of active, deployed, or rejected.
createdByA string representing the user who created the build, or SYSTEM if created non-interactively.
createdOnA string representing the UTC date when the build was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss).
rejectedByA string representing the user who rejected the build, or SYSTEM if rejected non-interactively.
rejectedOnA string representing the UTC date when the build was rejected, in ISO 8601 format (yyyy-MM-ddThh:mm:ss).
pipelineNameA string representing the name of the pipeline used by the build.
furthestStageA string representing the name the furthest stage the build has advanced to in the pipeline.
applicationIdAn integer representing the system-unique identifier of the application for the build.
applicationNameA string representing the system-unique name of the application for the build.
releaseIdAn integer representing the system-unique identifier of the release for the build.
releaseNumberA string representing the application-unique number of the release for the build.
releaseNameA string representing the name of the release for the build.

Deployment

PropertyFormat
idAn integer representing the system-unique identifier of the deployment.
planA string representing the name of the plan used for deployment.
statusA string consisting of pending, executing, succeeded, warned, or failed.
startedA 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.
endedA 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.
createdByA string representing the user who initiated the deployment, or SYSTEM if initiated non-interactively.
createdOnA string representing the UTC date when the deployment was initiated, in ISO 8601 format (yyyy-MM-ddThh:mm:ss).
canceledByA string representing the user who canceled the deployment (SYSTEM if canceled non-interactively), or null if the deployment was not canceled.
canceledOnA 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.
pipelineNameA string representing the name of the pipeline used by the deployment.
pipelineStageNameA string representing the name the stage in the pipeline used by the deployment.
environmentIdAn integer representing the system-unique identifier of the environment used by the deployment, or null if no environment is in context.
environmentNameA string representing the name of the environment used by the deployment, or null if no environment is in context.
applicationIdAn integer representing the system-unique identifier of the application for the deployment.
applicationNameA string representing the system-unique name of the application for the deployment.
releaseIdAn integer representing the system-unique identifier of the release for the deployment.
releaseNumberA string representing the application-unique number of the release for the deployment.
releaseNameA string representing the name of the release for the deployment.
buildIdAn integer representing the system-unique identifier of the build for the deployment.
buildNumberA 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:

FilterParameter Specification
ApplicationEither a key named applicationId with an integer value, or a key named applicationName with any value.
ReleaseEither a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value.
PipelineA key named pipelineName with any value.
StatusA 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:

InputParameter Specification
ApplicationRequired. Either a key named applicationId with an integer value, or a key named applicationName with any value.
Release NumberRequired. A key named releaseNumber with any value.
PipelineRequired. A key named pipelineName with any value.
Release NameOptional. A key named releaseName with any value.
VariablesOptional. 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:

InputParameter Specification
ApplicationRequired. Either a key named applicationId with an integer value, or a key named applicationName with any value.
Release NumberRequired. A key named releaseNumber with any value.
TemplateRequired. A key named template with any value.
Release NameOptional. A key named releaseName with any value.
Pipeline NameOptional. 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.
VariablesOptional. 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:

InputParameter Specification
ReleaseRequired. Either a key named releaseId with an integer value, or a key named releaseNumber with any value.
ApplicationRequired 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.
ReasonOptional. 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:

InputParameter Specification
ReleaseRequired. Either a key named releaseId with an integer value, or a key named releaseNumber with any value.
ApplicationRequired 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:

FilterParameter Specification
ApplicationEither a key named applicationId with an integer value, or a key named applicationName with any value.
ReleaseEither a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value.
BuildEither a key named buildId with an integer value, or a key named buildNumber with any value.
PipelineA key named pipelineName with any value.
StageA key named furthestStage with any value.
StatusA 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:

InputParameter Specification
ReleaseRequired. Either a key named releaseId with an integer value, or a key named releaseNumber with any value.
ApplicationRequired 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 NumberOptional. A key named buildNumber with any value; if not specified, the build number will be automatically generated.
VariablesOptional. 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:

FilterParameter Specification
ApplicationEither a key named applicationId with an integer value, or a key named applicationName with any value.
ReleaseEither a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value.
BuildEither a key named buildId with an integer value, or a key named buildNumber with any value.
DeploymentA key named deploymentId with an integer value.
PipelineA key named pipelineName with any value.
StageA key named pipelineStageName with any value.
EnvironmentEither a key named environmentId with an integer value, or a key named environmentName with any value.
StatusA 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:

InputParameter Specification
BuildRequired. Either a key named buildId with an integer value, or a key named buildNumber with any value.
ReleaseRequired 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.
ApplicationRequired 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 StageOptional. A key named toStage with any value. If not supplied, the next stage in the pipeline will be used.
ForceOptional. A key named force with a value of true or false.
Start TimeOptional. 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+
VariablesOptional. 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:

InputParameter Specification
BuildRequired. Either a key named buildId with an integer value, or a key named buildNumber with any value.
ReleaseRequired 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.
ApplicationRequired 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?