Component APIs

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
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