BuildMaster Release & Build Deployment API
  • 11 Mar 2024
  • 6 Minutes to read
  • Dark
    Light
  • PDF

BuildMaster Release & Build Deployment API

  • Dark
    Light
  • PDF

Article Summary

The Release & Build Deployment API offers a simple mechanism for creating releases, creating builds, and deploying builds.

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 a failed request (400 status).

All API endpoints are accessed through the following base URL:

/api/releases/...

🚀 Releases Endpoints

Create Release - Creates a release
Get Releases - Returns a list of all releases
Restore Release - Restores a release
Cancel Release - Cancels a release

🛠 Builds Endpoints

Create Build - Creates a build
Deploy Build - Deploys a build
Get Build - Returns a list of all builds
Reject Build - Rejects a build

âš™ Deployments Endpoint

Get Deployments - Returns a list of all deployments

Authentication

An API Key with the Release & Build Deployment permission is required to use this API.

It can be passed to each endpoint in one of four ways, depending on the content type of the expected request:

MethodName or KeyDetails
Request headerX-ApiKeyall content types
Querystring valuekeyall content types
Form valuekeyonly applications/x-www-form-urlencoded content type
JSON propertyAPI_Keyon root object, only application/json content type

To specify an API Key, use the request header (X-ApiKey), querystring (key), or api:«api-key» as the user name. See API Access and API Key to learn more.

🚀 Quick Example: Authenticating with curl

For example, to authenticate with the API key a1b2c3d4e5 to the create build endpoint, you could specify the API key as follows:

curl -X POST -H "X-ApiKey: a1b2c3d4e5" "/api/releases/builds/create"

If the provided API key is either missing, unknown/incorrect or does not have permission, the following message is returned:

The specified API key does not have the proper permissions to perform this action.

Data Specifications

📄 Note: PipelineId

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.

ReleaseInfo Object Properties

ReleaseInfo is a set of key/value pairs that correspond to the fields on a Release. It's used as output data for the Create Release and Get Releases endpoints, returning ReleaseInfo as a JSON-formatted object.

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.

JSON Object

{
    "id": 1,
    "number": "1.0.1",
    "name": "1.0.1",
    "sequence": 1,
    "status": "active",
    "createdBy": "MikeJones",
    "createdOn": "2024-03-04T09:03:43.9200000Z",
    "applicationId": 1,
    "applicationName": "ProfitCalculator",
    "pipelineName": "Release",
    "furthestBuildId": 3,
    "furthestBuildNumber": "2",
    "latestBuildId": 3,
    "latestBuildNumber": "2",
    "deployables": [],
    "furthestPackageId": 3,
    "furthestPackageNumber": "2",
    "latestPackageId": 3,
    "latestPackageNumber": "2",
    "releaseName": "1.0.1",
    "releaseNumber": "1.0.1"
}

BuildInfo Object Properties

BuildInfo is a set of key/value pairs that correspond to the fields on a Build. It's used as output data for the Create Build and Get Build endpoints, returning BuildInfo as a JSON-formatted object.

PropertyFormat
idAn integer representing the system-unique identifier of the build.
buildNumberA string representing the build-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 of 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.

JSON Object

{
    "id": 1,
    "number": "3",
    "status": "active",
    "createdBy": "API",
    "createdOn": "2024-03-05T02:46:56.0800000Z",
    "applicationId": 2,
    "applicationName": "TaxCalculator",
    "pipelineName": "Release",
    "releaseId": 4,
    "releaseNumber": "1.0.1",
    "releaseName": "1.0.1",
    "buildNumber": "3"
}

DeploymentInfo Object Properties

DeploymentInfo is a set of key/value pairs that correspond to the fields on a Release. It's used as both input and output data for the Deploy Build and Get Deployments endpoints, returning DeploymentInfo as a JSON-formatted object.

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 of 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.
{
    "id": 1,
    "plan": "Deploy",
    "status": "succeeded",
    "started": "2024-03-04T09:31:20.5100000Z",
    "ended": "2024-03-04T09:31:20.6100000Z",
    "createdBy": "SYSTEM",
    "createdOn": "2024-03-04T09:31:15.4900000Z",
    "pipelineName": "Release",
    "pipelineStageName": "Integration",
    "applicationId": 1,
    "applicationName": "TaxCalculator",
    "releaseId": 1,
    "releaseNumber": "1.0.1",
    "releaseName": "1.0.1",
    "buildId": 1,
    "buildNumber": "2",
    "packageId": 1,
    "packageNumber": "2"
}

Was this article helpful?

What's Next