Application APIs

APIs for Applications.

Get a List Applications

This call returns an array of JSON objects representing each Application to which the logged-in User has access.

If the “all” parameters is not specified then only the Applications associated with the User’s home Domain are listed. If the “all” parameter is specified by setting it to “y” then the result includes the Applications in all accessible Subdomains.

REST Api Endpoint

HTTP Verb URL
GET /dmadminweb/API/applications

Parameters

Name Located in Value Required Schema
all query y or n No string

Application Result Object

Name Type Description Required
success boolean Is true or false depending on the success or failure of the query. If success is false, then result is not returned and a text field named “error” is sent instead. No
result An array of Application Objects (see below). JSON array of Application Object one for each environment returned by the query (if success is true). No

Application Object

Name Type Description Required
completed string The date/time of the last deployment of this Application into the Environment. No
deploymentid integer The ID of the last deployment of this Application into the Environment. An ID of 0 indicates that the Application has been manually associated with the environment. No
exitcode integer The exit code of the last deployment of this Application into the Environment. No
id integer The internal object ID of the Application Base Version. No
name string The name of the Application Base Version. No
predecessorid integer The ID of the previous Application Version. No
versionid integer The ID of the Application Version. No
versionname string The name of the Application Version No

Application Version Object

Name Type Description Required
id integer Is the internal Application ID (app_id). No
name string Is the name of the Application Version. No
summary string Is the summary text associated with the Application Version. No

Retrieve specific Application or Application Version

This call returns a JSON object representing the specified Application. The resulting JSON will vary slightly depending on whether the specified Application is an Application Base Version or an Application Version.

REST Api Endpoint

HTTP Verb URL
GET /dmadminweb/API/application/{identifier}

Parameters

Name Located in Value Required Schema
latest query If latest is set to “Y” then the latest version of the Application is returned. To use this flag, the specified identifier must refer to a Application Base Version, otherwise the flag has no effect. No string
branch query If branch is set along with latest then the latest version on the specified branch name is returned. Yes string
identifier path Is the identifier of the Application. Either its name, its qualified name with its parent Domains included in dot notation (i.e GLOBAL.Product) or its internal ID. Yes string

Application Version Result Object

Name Type Description Required
success boolean Is true or false depending on the success or failure of the query. If success is false then result is not returned and a text field named “error” is returned instead. No
result An array of Application Versions (see below). JSON array of Application Versions No

Application Version Object

Name Type Description Required
id integer Is the internal Application ID (app_id). No
name string Is the name of the Application Version. No
summary string Is the summary text associated with the Application Version. No

Create New Application Version

This call creates a new Application Version. The new Application Version inherits all the attributes of the predecessor Application. In order for this to work through the permission model, there has to be a Create Version Task either in the Domain in which the specified Application is located or in any of the parent Domains as long as the Create Version Task is set to be “available” to Subdomains.

This mechanism ensures that the invoking user has permission to create a new version of the Application (since the permissions are checked against the Task) and also the target Domain (i.e. the Domain in which the new Application is created) is determined from the Task. Also, by specifying the Task to execute, any pre and post link Actions are executed just as if the Task had been invoked via the Web UI.

REST Api Endpoint

HTTP Verb URL
GET /dmadminweb/API/new/appver/{app_id}

Parameters

Name Located in Value Required Schema
app_id path Is the ID of the_Application_which will be the parent of the new_Application Version_. Either its name, its qualified name with its parent_Domains_included in dot notation (i.e. GLOBAL.products) or its internal ID. The newly created_Application Version_will inherit all the attributes from this_Application_. Yes integer
task query Is the identifier of a Task to execute in order to create the new Application Version. Either its name, its qualified name with its Domain and any parent Domains included in dot notation (i.e. GLOBAL.Product) or its internal ID. If the Task is not specified, the first accessible Create Version Task within the Application’s Domain is used (or any Create Version Task in parent Domains as long as they are set to be “available” to Subdomains). No string

Response Success Object

This Object contains the success/failed return code and an error message.

Name Type Boolean Description Required
success boolean Success or Failure. Yes
error string Error message returned from API. No

Replace Component

Replace a Component within an Application. This call replaces a specific Component within an Application. You can use this to update the version of a Component within an Application by replacing the old Component Version with the new.

REST Api Endpoint

HTTP Verb URL
GET /dmadminweb/API/new/replace/{app_id}/{old_comp_id}/{new_comp_id}

Parameters

Name Located in Value Required Schema
app_id path Is the ID of the_Application_with which the old_Component_ID (Comp_id) is associated. Either its name, its qualified name with its parent Domains included in dot notation, (i.e GLOBAL.Product) or its internal ID. Yes integer
old_comp_id path Is the ID of the Component (Comp_id) which is to be replaced. Either its name, its qualified name with its parent_Domains_ included in dot notation (i.e. GLOBAL.Products) or its internal ID. Yes integer
new_comp_id path Is the ID of the Component which will replace old Component ID (comp_id). Either its name, its qualified name with its parent_Domains_ included in dot notation (i.e GLOBAL.Product) or its internal ID. Yes integer

Response Success Object

This Object contains the success/failed return code and an error message.

Name Type Boolean Description Required
success boolean Success or Failure. Yes
error string Error message returned from API. No

Approving an Application

This call allows the API to approve/reject an Application for a specified Domain. In order for this to work through the permission model, there has to be an Approve Task either in the Domain in which the specified Application is located or in any of the parent Domains as long as the Approve Task is set to be “available” to Subdomains.

This mechanism ensures that the invoking user has permission to approve the Application (since the permissions are checked against the named Task) and also the target Domain (i.e. the Domain to which the Application is being approved/rejected) is determined from the Task. Also, by specifying the Task to execute, any Pre and Post Actions are executed just as if the Task had been invoked via the Web UI.

REST Api Endpoint

HTTP Verb URL
GET /dmadminweb/API/approve/{app_id}

Parameters

Name Located in Description Required Schema
app_id path Is the identifier of the_Application_to be approved/rejected. Either its name, its qualified name with its parent_Domains_ included in dot notation (i.e.GLOBAL.Products) or its internal ID. Yes integer
task query Is the identifier of a task to execute in order to approve the Application. Either its name, its qualified name with its Domain and any parent Domains included in dot notation (i.e GLOBAL.Product) or its internal ID. If the Task is not specified, the first accessible Approve Task within the Application’s Domain is used or any Approve task in the parent Domains as long as they are set to be “available” to Subdomains. No string
approve query Is optional. If specified and set to N for “no,” then the Application is rejected. If this parameter is not specified or is set to Y for “yes,” then the Application is approved. No string
notes query Any free-text notes that should be associated with the approval/rejection. No string

Response Success Object

This Object contains the success/failed return code and an error message.

Name Type Boolean Description Required
success boolean Success or Failure. Yes
error string Error message returned from API. No

Associate an Application to an Environment

This call associates an existing Application with an Environment. This association allows the Application (or any of its Versions) to be deployed to that Environment. An Application needs to be assigned to an Environment before it can be deployed to that Environment.

REST Api Endpoint

HTTP Verb URL
GET /dmadminweb/API/approve/{app_id}

Parameters

Name Located in Value Required Schema
app_id path Is the identifier of the_Application_to be assigned. Either its name, its qualified name with its parent_Domains_ included in dot notation (i.e GLOBAL.Product) or its internal ID. Yes integer
env_id path Is the identifier of the_Environment_to which the_Endpoint_should be assigned. Either its name, its qualified name with its parent_Domains_ included in dot notation (i.e GLOBAL.Product) or its internal ID. Yes string

Response Success Object

This Object contains the success/failed return code and an error message.

Name Type Boolean Description Required
success boolean Success or Failure. Yes
error string Error message returned from API. No

Disassociates an Application from an Environment

This call removes, or disassociates, an Application from an Environment. Once the Application has been disassociated from the Environment neither it nor any of its Versions can be deployed to that Environment.

Disassociating an Application from an Environment does not physically remove the Application from the Environment. It simply prevents deploying any Version of the Application to the Environment.

REST Api Endpoint

HTTP Verb URL
GET /dmadminweb/API/unassign/application/{app_id}/{env_id}

Parameters

Name Located in Description Required Schema
app_id path Is the identifier of the_Application_to be assigned. Either its name, its qualified name with its parent_Domains_ included in dot notation (i.e GLOBAL.Product) or its internal ID. Yes integer
env_id path Is the identifier of the_Environment_to which the server should be assigned. Either its name, its qualified name with its parent_Domains_ included in dot notation (i.e GLOBAL.Product) or its internal ID. Yes string

Response Success Object

This Object contains the success/failed return code and an error message.

Name Type Boolean Description Required
success boolean Success or Failure. Yes
error string Error message returned from API. No
Last modified June 28, 2020: run markdownlint tidy (1259dc6)