Application Management API

This API is available in BuildMaster 7.0.19 and later.

The Application Management API has Endpoints to help list, create, update, and purge applications, and are intended to automate the setup and management of applications in your BuildMaster instance.

The primary use cases of this API are to:

• Create a Blank Application
• Clone an Application
• Create an Application from a Template
• Change Application Settings
• Move Applications to New Group
• Deactivate an Application
• Purge an Application
• List All Applications

This API is only intended to update application settings; see the Variables Management API and Release & Build Deployment API to manage other application configuration.

Security & API Keys

An API Key with the Application Management permission is required to use this API.

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

Endpoint Specifications

Create Application Endpoint

The Create Application Endpoint can create a blank application.

Create Application Request

• Request Type: POST
• Request URL: /api/applications/create
• Request Body: ApplicationInfo Object
• Note that:
  • An API key must be specified as part of the request
  • Querystring parameters may be used for ApplicationInfo Object Properties instead of the Body

Create Application Response

Response	Details
200 (Success)	body will contain a ApplicationInfo Object
400 (Invalid Input)	indicates invalid or missing properties on the ApplicationInfo Object; the body will provide some details as text
403 (Unauthorized API Key)	indicates a missing, unknown, or unauthorized API Key; the body will be empty
500 (Server Error)	indicates an unexpected error; the body will contain the message and stack trace, and this will also be logged

Clone Application

The Clone Application Endpoint can clone an existing application.

Clone Application Request

• Request Type: POST
• Request URL: /api/applications/clone
• Request Body: CloneApplication Object
• Note that:
  • An API key must be specified as part of the request
  • Querystring parameters may be used for CloneApplication Object Properties instead of the Body

Clone Application Response

Response	Details
200 (Success)	body will contain a ApplicationInfo Object
400 (Invalid Input)	indicates invalid or missing properties on the CloneApplication Object; the body will provide some details as text
403 (Unauthorized API Key)	indicates a missing, unknown, or unauthorized API Key; the body will be empty
500 (Server Error)	indicates an unexpected error; the body will contain the message and stack trace, and this will also be logged

Import Application Endpoint

The Import Application Endpoint can create an application from an exported package (i.e., template, sample, or backup).

Import Application Request

• Request Type: POST
• Request URL: /api/applications/import
• Request Body: ImportApplication Object
• Note that:
  • An API key must be specified as part of the request
  • Querystring parameters may be used for CloneApplication Object Properties instead of the Body

Import Application Response

Response	Details
200 (Success)	body will contain a ApplicationInfo Object
400 (Invalid Input)	indicates invalid or missing properties on the ImportApplication Object; the body will provide some details as text
403 (Unauthorized API Key)	indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error)	indicates an unexpected error; the body will contain the message and stack trace; this will also be logged

Update Application Endpoint

The Update Application Endpoint can update properties of an existing application.

Update Application Request

• Request Type: POST
• Request URL: ` /api/applications/update
• Request Body: ApplicationInfo Object
• Note that:
  • An API key must be specified as part of the request
  • Querystring parameters may be used for ApplicationInfo Object Properties instead of the Body

Update Application Response

Response	Details
200 (Success)	body will contain a ApplicationInfo Object
400 (Invalid Input)	indicates invalid or missing properties on the ApplicationInfo Object; the body will provide some details as text
403 (Unauthorized API Key)	indicates a missing, unknown, or unauthorized API Key; the body will be empty
500 (Server Error)	indicates an unexpected error; the body will contain the message and stack trace, and this will also be logged

Purge Application Endpoint

The Purge Application Endpoint can purge an existing application

Purge Application Request

• Request Type: POST
• Request URL: ` /api/applications/purge
• Querystring Parameters: application (name or id to purge)
• Note that:
  • An API key must be specified as part of the request
  • An empty body is acceptable, but you can post key/value pairs in the body instead of the querystring

Purge Application Response

Response	Details
200 (Success)	body will be empty
400 (Invalid Input)	indicates application parameter is missing
403 (Unauthorized API Key)	indicates a missing, unknown, or unauthorized API Key; the body will be empty
500 (Server Error)	indicates an unexpected error; the body will contain the message and stack trace, and this will also be logged

List Application Endpoint

The List Application Endpoint can list applications.

List Application Request

• Request Type: GET, POST, or HEAD
• Request URL: ` /api/applications/update
• Note that:
  • An API key must be specified as part of the request
  • No parameters (aside from API key) are used in this request

List Application Response

Response	Details
200 (Success)	body will contain an array of ApplicationInfo Object
403 (Unauthorized API Key)	indicates a missing, unknown, or unauthorized API Key; the body will be empty
500 (Server Error)	indicates an unexpected error; the body will contain the message and stack trace, and this will also be logged

Data Specifications

ApplicationInfo Properties

ApplicationInfo is a set of key/value pairs that correspond to the fields on the Application > Basic Settings and Advanced Settings pages. It's used as both input and output data for various endpoints:

• Output: The Create, Update, and List endpoints return ApplicationInfo as a JSON-formatted object; all values are returned
• Input: The Update endpoint receives ApplicationInfo as either a JSON-formatted object, querystring parameter, or form-encoded data; a missing property indicates that the value should not be updated

Note that some values are optional (indicated by string?), and may be set to null or an empty string.

Property	Format	Notes
id	int	Internal ID of application
name	string	Must be unique across the system
description	string?
groupName	string?	null to be ungrouped
active	bool	false indicates a deactivated application
setupTemplate	string?	Name of the Setup template to use or null to not use one
buildNumberScheme	string	Sequential, DateTimeBased, or Unique
releaseUsage	string	Required, Optional, or Disabled
defaultReleaseTemplate	string?	Name of the or null to use the Default template
allowIssues	bool
displayIssues	bool
displayPipelines	bool
displayScripts	bool
displayConfiguration	bool
displayDatabase	bool
buildPageDescription	string?
artifactUsage	string	Default, None, FileSystem, or AssetDirectory
artifactAssetDirectory	string?	When artifactUsage is AssetDirectory, this field must be the name of an Asset Directory secure resource; otherwise null
raft	string?	Name of a raft or null to use the Default raft

CloneApplication Properties

CloneApplication is a set of key/value pairs that provide direction on creating a new application. It's used as input for the Clone endpoint.

Property	Format	Notes
name	string	The name of the new application to create
from	string	The name or id of an application to clone
raft	string?	Name of a raft or null to use the Default raft

This will behave the same as cloning that application from the UI.

ImportApplication Properties

ImportApplication is a set of key/value pairs that provide direction on creating a new application. It's used as input for the import endpoint.

Property	Format	Notes
name	string	The name of the new application to create
packageSource	string	The name of a Universal Feed secure resource
packageId	string	The id of the package to import (not the name)
packageVersion	string	The version of the package to import or latest for the latest version
importHistory	bool	When set to true, historical data in the package like Build and Executes will be imported
overwrite	bool	When set to false, if an application with the specified name already exists, an error will occur; otherwise, any items in the Package will overwrite the configuration
raft	string?	Name of a raft or null to use the "Default" raft

Depending on the value of the properties, this behaves like creating an application from a template, reapplying a template, creating a sample application, or restoring an application from a backup.

HOWTO: Create a Blank Application (PowerShell)

Creates a new application named MyNewApp with default configuration.

Invoke-WebRequest -Uri "https://buildmaster.local/api/applications/create?key=mySecretKey&name=MyNewApp" -Method POST

HOWTO: Clone an Application (Curl)

Clones existing application MyApp into a new application named MyNewApp.

curl -d key=mySecretKey -d name=MyClonedApp -d from=MyApp https://buildmaster.local/api/applications/clone

HOWTO: Change Application Settings (PowerShell)

Updates the description and artifact usage settings on application named MyApp. Only specified properties will be updated.

$postParams = @{`
key='mySecretKey';
name='MyApp';`
description='New description of my app';`
artifactUsage='AssetDirectory';`
artifactAssetDirectory='global::MyAssetDirName'
}
Invoke-WebRequest -Uri https://buildmaster.corp/api/applications/update -Method POST -Body $postParams