BuildMaster Documentation

Release & Package Deployment

The Release & Package Deployment API offer a simple mechanism for creating releases, creating release packages, and deploying release packages.

This API endpoint should be used instead of the Native API Methods when possible, as they are much easier to use and will likely not change.

For security and simplicity, these endpoints require that an API Key is created and passed into each request.

Check out these steps retrieving deployment status by package number through the Release and Package deployment API.

Data Specification

This endpoint receives data entirely as key/value parameters and sends data using the following JSON objects:

  • Release
  • Package
  • 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.
furthestPackageId An integer representing the system-unique identifier of the active or deployed package that has made it furthest in the pipeline for the release.
furthestPackageNumber A string representing the application-unique number of the active or deployed package that has made it furthest in the pipeline for the release.
latestPackageId An integer representing the system-unique identifier of the active or deployed package that was most recently created.
latestPackageNumber A string representing the application-unique number of the active or deployed package that was most recently created.
Property Format
id An integer representing the system-unique identifier of the package.
number A string representing the release-unique identifier of the package.
status A string consisting of active, deployed, or rejected.
createdBy A string representing the user who created the package, or SYSTEM if created non-interactively.
createdOn A string representing the UTC date when the package was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss).
rejectedBy A string representing the user who rejected the package, or SYSTEM if rejected non-interactively.
rejectedOn A string representing the UTC date when the package 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 package.
pipelineName A string representing the name of the pipeline used by the package.
furthestStage A string representing the name the furthest stage the package has advanced to in the pipeline.
applicationId An integer representing the system-unique identifier of the application for the package.
applicationName A string representing the system-unique name of the application for the package.
releaseId An integer representing the system-unique identifier of the release for the package.
releaseNumber A string representing the application-unique number of the release for the package.
releaseName A string representing the name of the release for the package.
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.
packageId An integer representing the system-unique identifier of the package for the deployment.
packageNumber A string representing the release-unique number of the package for the deployment.

Endpoint Specification

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.

Get Packages

GET or POST /api/releases/packages

Returns a status of 200 and a body with an array of package 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.
Package Either a key named packageId with an integer value, or a key named packageNumber 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 Release Package

POST or PUT /api/releases/packages/create

Returns a status of 200 and a body with a package 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.
Package Number Optional. A key named packageNumber with any value; if not specified, the package 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/packages/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.
Package Either a key named packageId with an integer value, or a key named packageNumber 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 Package

POST or PUT /api/releases/packages/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
Package Required. Either a key named packageId with an integer value, or a key named packageNumber with any value.
Release Required if packageNumber 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.
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 Release Package

POST or DELETE /api/releases/packages/reject

Returns a status of 200 if the package was rejected:

Input Parameter Specification
Package Required. Either a key named packageId with an integer value, or a key named packageNumber with any value.
Release Required if packageNumber 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.

Get Deployment statuses by Package Number

Step 1: Create an API Key

To enable the API, you must create an API key within BuildMaster. Simply navigate to "Administration" > "API Keys & Access Logs" and create an API key. Make sure to enable "Grant access to Release & Deployment API" so the key you create has access to the required API endpoint.

Step 2: Get the Deployment Details

Once you have an API key, you can perform a Get Deployments request. There are several filters you can apply. In this example, we'll apply the Application, Release, and Package filters.

GET /api/releases/packages/deployments?applicationName=HDARS&releaseNumber=1.8.3&packageNumber=1&key=hLJA9IFeV7MKzVfeaaSktg==

The response will look something like this. In this case, we can see that the deployment failed!

[
    {
        "id": 1179,
        "plan": "Deploy HDARS",
        "status": "failed",
        "started": "2017-03-17T17:09:13.2170000",
        "ended": "2017-03-17T17:09:53.3800000",
        "createdBy": "Admin",
        "createdOn": "2017-03-17T17:09:11.5270000",
        "pipelineId": 8,
        "pipelineName": "HDARS",
        "pipelineStageName": "Testing",
        "environmentId": 2,
        "environmentName": "Testing",
        "applicationId": 8,
        "applicationName": "HDARS",
        "releaseId": 10,
        "releaseNumber": "1.8.3",
        "releaseName": "1.8.3",
        "packageId": 81,
        "packageNumber": "1"
    }
]