BuildMaster Documentation

Release & Build Deployment

  • Last Modified: 2019-07-17

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
  • Build
  • Deployment
Property Format
id An integer representing the system-unique identifier of the release.
number A string representing the application-unique identifier of the release.
name 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.
pipelineId An integer representing the system-unique identifier of the pipeline used by 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.
Property Format
id An integer representing the system-unique identifier of the build.
number 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).
pipelineId An integer representing the system-unique identifier of the pipeline used by the build.
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.
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.
pipelineId An integer representing the system-unique identifier of the pipeline used by the deployment.
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.

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 Either a key named pipelineId with an integer value, or 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. Either a key named pipelineId with an integer value, or 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.
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 Either a key named pipelineId with an integer value, or 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 Either a key named pipelineId with an integer value, or 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 the timestamp 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.

Is this documentation incorrect or incomplete? Help us by contributing!

This documentation is licensed under CC-BY-SA-4.0 and stored in GitHub.

Generated from commit 2fde8bec on master