Component APIs

APIs for Components.

Retrieve a Component

Retrieve specific Component or Component version. This call returns a JSON Object representing the specified Component. It is useful to determine the Application(s) which include the Component, whether the Application is approved, which other Components are used alongside the specified Component and so on.

REST Api Endpoint

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

Parameters

Name Located in Value Required Schema
latest query If latest is set to Y, for “Yes”, then the latest version of the Component is returned. To use this flag, the specified identifier must refer to a Component 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 Component. Either its name, its qualified name with its parent Domains included in dot notation (i.e. GLOBAL.Products) or its internal ID. Yes string

Component 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 Component Objects. JSON array of Component Object one for each environment returned by the query (if success is true). No

Component Object

Name Type Description Required
id integer Is the Component’s internal ID. No
lastbuild integer Is the last build number associated with this Component (0 if never built or no associated build job). No
name string Is the name of the Component. No
summary string Is the summary text associated with the Component. No
domain string The fully-qualified domain name of the Domain in which the Component is located. No
Component_id string Is the internal ID of the_Component_. No
Component_name string Is the name of the_Component_. No
owneruser string If the “owner” of the Component is a User, then this is the name of that User. No
ownergroup string If the “owner” of the Component is a Group, then this is the name of that Group. No
predecessor Component Version Parent Component or Predecessor. No

Component Predecessor

Only returned for Component Versions. A JSON Object represents the predecessor of this Component.

Name Type Description Required
id integer Is the internal Component ID. No
name string Is the name of the predecessor Component. No
summary string Is the summary text associated with the predecessor Component. No
versions Component Version A JSON Object representing the parent Component Version of this Component. No

Component Version Result

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 Component Version with details. Full details for a specific Component Version. No

Component Version Full Detail

A JSON object represents the Component being retrieved.

Name Type Description Required
branch string Is the name of the branch on which this Component is located. If no branch is specified, this string is zero length. No
domain string The fully-qualified domain name of the Domain in which the Component is located. No
id integer The internal id of the Component or Component Version. No
lastbuild integer Last Build number that created the Component or Component Version. No
name string The name of the Component or Component Version. No
owneruser string If the “owner” of the Component is a User, then this is the name of the User. No
ownergroup string If the “owner” of the Component is a Group, then this is the name of that Group. No
requests Request A change request Object. No
summary string Is the summary text associated with the Component Version. No
component_versions Component Version A specific_Component_ with a unique identifier. No
applications Application Version with full details All details for the Application Version. No
predecessor The parent of the Component An earlier Component Version. No

Application Version Results Full Detail

Name Type Description Required
approvals An Array of Approvals See Approve or Reject Object. No
rejections An Array of Rejections See Approve or Reject Object. No
summary string Is the summary text associated with the application. No
branch string Is the name of the branch on which this application is located (if an application version. If no branch is specified, this string is zero length. No
components Component See Component Object. No
requests request See Request Object. No
application_versions Array of Related_Application Versions_ See_Application_ Object. 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

Request

Name Type Description Required
title string Is the description of the Change Request. No
id integer Is the ID of the Change Request as known by the external change tracking system. No
status string Is the status of the Change Request. No
api_url string Is the URL of the API call to the external change tracking system that is required to return more data about the specified Change Request. No
html_url string Is the URL of the page in the external change tracking system which details more information about the change request. No

Approval Results

Name Type Description Required
domain string Domain that approval was made in. No
note string Comments about the approval. No
timestamp integer When the approval was preformed. No
user string Userid that did the approval. No

Rejection Results

Name Type Description Required
domain string Domain that rejection was made in. No
note string Comments about the rejection. No
timestamp integer When the rejection was preformed. No
user string Userid that did the rejection. No

Create New Component Version

This call creates a new Component Version. The new Component inherits all the attributes of the predecessor Component including its Domain.

REST Api Endpoint

HTTP Verb URL
GET /dmadminweb/API/new/compver/{comp_id}

Parameters

Name Located in Description Required Schema
comp_id path Is the ID of the_Component_which will be the parent of the new_Component Version_. Either its name, its qualified name with its parent_Domains_included in dot notation (i.e. GLOBAL.Product) or its internal ID. The newly created_Component Version_will inherit all the attributes from this_Component_. Yes integer

Component 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 Component Objects. JSON array of Component Object one for each environment returned by the query (if success is true). No

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 a Build with a Component

This call associates a build number with a specified Component. It is typically used with CD Engines to notify that a new build has been performed. If the Component is associated with an approved Application then a new version of the Component and Application is created automatically and the new Component version replaces the old Component version in the newly created Application version.

In order for this to work through the permission model, the associated “Create Application Version” Task needs to be specified. This ensures that the invoking user has permission to create a new version of the Application (since the permissions are checked against the named 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/buildid/{comp_id}/{build_id}

Parameters

Name Located in Value Required Schema
comp_id path Is the ID of a_Component Base Version_. The latest version of this_Component_will be found and associated to the build with that_Component Version_. If “branch” is specified then the latest version on the branch is located. The_Component_can be specified using either its name, its qualified name with its parent_Domains_ included in dot notation (i.e. GLOBAL.Products) or its internal ID. Yes integer
build_id path Is the numeric build ID to associate with the latest version of_Component_ID (comp_id). Yes integer
taskname query Is the identifier of a “Create New Application 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. Yes string
commit query Is the commit ID which triggered the build. No string
issue query Is a change request id to associate with this build. If you add an issue then the specified Component must have an associated Change Request Data Source associated with it. This is because the API will query the change tracking tool in order to retrieve the description of the change and the current status. If the Component does not have such a Change Request Data Source an error is returned. You can specify one or more issue parameters if you need to associate multiple change requests with this build or use the issues parameter to specify multiple change requests. No string
issues query Is a comma-separated list of change request ids. This is equivalent to specifying multiple issue parameters. No string
file query Is a filename to record against the build. This is typically a file that was changed that resulted in a build being performed. You can specify one or more file parameters if you need to associate multiple files with this build or use the files parameter to specify multiple files. No string
files query Is a comma-separated list of files. This is equivalent to specifying multiple file parameters. No string

Component 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 Component Objects. JSON array of Component Object one for each environment returned by the query (if success is true). No

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 15, 2020: markdown tidy (81314aa)