From 887c396166682d6cf967a971654286ce2b2cd3a1 Mon Sep 17 00:00:00 2001 From: TracyRagan Date: Mon, 15 Jun 2020 08:26:09 -0600 Subject: [PATCH] API Docs --- .../{Intro.md => Intro and Logging in.md} | 2 +- content/en/userguide/restapi/applications.md | 36 +- content/en/userguide/restapi/components.md | 39 +-- content/en/userguide/restapi/credentials.md | 110 +++--- .../en/userguide/restapi/deployment-log.md | 27 +- content/en/userguide/restapi/deployment.md | 35 +- content/en/userguide/restapi/endpoints.md | 110 +++--- content/en/userguide/restapi/environments.md | 54 ++- content/en/userguide/restapi/login.md | 34 -- content/en/userguide/restapi/models.md | 329 ------------------ content/en/userguide/restapi/users.md | 54 ++- .../reusable/Model Application Result.md | 4 +- .../Model Application Version Full.md | 14 +- .../Model Application Version Result.md | 35 +- .../reusable/Model Application Version.md | 2 +- .../reusable/Model Approve or Reject.md | 20 +- .../reusable/Model Component Predecessor.md | 4 +- .../reusable/Model Component Result.md | 6 + .../reusable/Model Component Version Full.md | 12 +- .../Model Component Version Result.md | 4 +- .../en/userguide/reusable/Model Component.md | 23 +- .../reusable/Model Deployment Log Result.md | 4 +- .../reusable/Model Deployment Log.md | 10 +- .../reusable/Model Deployment Result.md | 2 +- .../en/userguide/reusable/Model Endpoints.md | 2 +- .../reusable/Model Environment Result.md | 2 +- .../userguide/reusable/Model Environment.md | 6 +- .../reusable/Model Environments Result.md | 4 +- .../en/userguide/reusable/Model Request.md | 4 +- .../en/userguide/reusable/Model Success.md | 4 +- 30 files changed, 256 insertions(+), 736 deletions(-) rename content/en/userguide/restapi/{Intro.md => Intro and Logging in.md} (99%) delete mode 100644 content/en/userguide/restapi/login.md delete mode 100644 content/en/userguide/restapi/models.md create mode 100644 content/en/userguide/reusable/Model Component Result.md diff --git a/content/en/userguide/restapi/Intro.md b/content/en/userguide/restapi/Intro and Logging in.md similarity index 99% rename from content/en/userguide/restapi/Intro.md rename to content/en/userguide/restapi/Intro and Logging in.md index d5efbe0b..46e1e802 100644 --- a/content/en/userguide/restapi/Intro.md +++ b/content/en/userguide/restapi/Intro and Logging in.md @@ -57,7 +57,7 @@ To use the ID, just place it where you would normally place the object's name. T curl --data "all=Y" --cookie c:\temp\session.txt http://mac:8080/dmadminweb/API/servers ~~~ -##Login +## Login When issuing calls to the API, the client application must either first issue a "login" call, specifying the username and password or must specify the username and password in each individual call to the API. diff --git a/content/en/userguide/restapi/applications.md b/content/en/userguide/restapi/applications.md index d8bf526f..7733d6d4 100644 --- a/content/en/userguide/restapi/applications.md +++ b/content/en/userguide/restapi/applications.md @@ -25,6 +25,8 @@ If the "all" parameters is not specified then only the _Applications_ associated | all | query | y or n | No | string | {{% include "userguide/reusable/Model Application Result.md" %}} +{{% include "userguide/reusable/Model Application.md" %}} +{{% include "userguide/reusable/Model Application Version.md" %}} ## Retrieve specific _Application_ or _Application Version_ @@ -45,11 +47,8 @@ This call returns a JSON object representing the specified _Application_. The re | 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 | -**Responses** - -| Return Code | Return Code Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [application_version_result](/userguide/restapi/models/#application_version_result) | +{{% include "userguide/reusable/Model Application Version Result.md" %}} +{{% include "userguide/reusable/Model Application Version.md" %}} ## Create New Application Version @@ -80,7 +79,7 @@ Replace a _Component_ within an _Application_. This call replaces a specific _Co | HTTP Verb | URL | | ---- | ----------- | -| GET | /dmadminweb/API/new/replace/{app_id}/{old_comp_id}/{new_comp_id} |~~~ +| GET | /dmadminweb/API/new/replace/{app_id}/{old_comp_id}/{new_comp_id} | **Parameters** @@ -91,12 +90,7 @@ Replace a _Component_ within an _Application_. This call replaces a specific _Co | 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 | -**Responses** - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/userguide/restapi/models/#success) | - +{{% include "userguide/reusable/Model Success.md" %}} ## Approving an Application @@ -120,11 +114,7 @@ This mechanism ensures that the invoking user has permission to approve the _App | 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 | -**Responses** - -| Return Code | Return Code Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/userguide/restapi/models/#success) | +{{% include "userguide/reusable/Model Success.md" %}} ## Associate an _Application_ to an _Environment_ @@ -144,11 +134,7 @@ This call associates an existing _Application_ with an _Environment_. This assoc | 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 | -**Responses** - -| Return Code | Return Code Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/userguide/restapi/models/#success) | +{{% include "userguide/reusable/Model Success.md" %}} ## Disassociates an _Application_ from an _Environment_ @@ -170,8 +156,4 @@ Disassociating an _Application_ from an _Environment_ does not physically remove | 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 | -**Responses** - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/userguide/restapi/models/#success) | +{{% include "userguide/reusable/Model Success.md" %}} diff --git a/content/en/userguide/restapi/components.md b/content/en/userguide/restapi/components.md index 158b4976..2e403ed2 100644 --- a/content/en/userguide/restapi/components.md +++ b/content/en/userguide/restapi/components.md @@ -1,14 +1,14 @@ --- title: "Component APIs" linkTitle: "Component APIs" -weight: 20 +weight: 14 description: > 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_(s) are approved, which other _Components_ are used in _Application_s alongside the specified _Component_ and so on. +## 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** @@ -24,13 +24,18 @@ Retrieve specific _Component_ or _Component_ version. This call returns a JSON o | 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 | -**Responses** +{{% include "userguide/reusable/Model Component Result.md" %}} +{{% include "userguide/reusable/Model Component.md" %}} +{{% include "userguide/reusable/Model Component Predecessor.md" %}} +{{% include "userguide/reusable/Model Component Version Result.md" %}} +{{% include "userguide/reusable/Model Component Version Full.md" %}} +{{% include "userguide/reusable/Model Application Version Full.md" %}} +{{% include "userguide/reusable/Model Application Version.md" %}} +{{% include "userguide/reusable/Model Request.md" %}} +{{% include "userguide/reusable/Model Approve or Reject.md" %}} -| Return Code | Return Code Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [_Component__version_result](/userguide/restapi/models/#_Component__version_result) | -##Create New _Component Version_ +## 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_. @@ -46,11 +51,8 @@ This call creates a new _Component Version_. The new _Component_ inherits all th | ---- | ---------- | ----------- | -------- | ---- | | 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 | -**Responses** - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](userguide/restapi/models/#success) | +{{% include "userguide/reusable/Model Component Result.md" %}} +{{% include "userguide/reusable/Model Success.md" %}} ## Associate a Build with a _Component_ @@ -69,17 +71,14 @@ In order for this to work through the permission model, the associated "Create _ | Name | Located in | Value | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | -| comp_id | path | Is the ID of a BASE _Component_. 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 | +| 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 | +| 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 | -**Responses** - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/userguide/restapi/models/#success) | +{{% include "userguide/reusable/Model Component Result.md" %}} +{{% include "userguide/reusable/Model Success.md" %}} diff --git a/content/en/userguide/restapi/credentials.md b/content/en/userguide/restapi/credentials.md index 8249c2cb..4b5e4536 100644 --- a/content/en/userguide/restapi/credentials.md +++ b/content/en/userguide/restapi/credentials.md @@ -1,97 +1,75 @@ --- -title: "Credentials" -linkTitle: "Credentials" -weight: 70 +title: "Credential APIs" +linkTitle: "Credentials APIs" +weight: 16 description: > Create a new Crendential. --- -### /dmadminweb/API/new/credential/{cred_id} +## Create a _Credential_ +This call creates a new credential. All of the attributes of the new _Credential_ are set through parameters to the API. If "_Domain_" is not specified then the _Environment_ is created in the logged in _User's_ home _Domain_. -#### GET +**REST Api Endpoint** -##### Summary +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/new/credential/{cred_id} | -Create a New Credential -##### Description - -This call creates a new credential. All of the attributes of the new credential are set through parameters to the API. - -If "domain" is not specified then the environment is created in the logged in user's home domain. - -##### Parameters +**Parameters** | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | -| cred_id | path | Is the name of the credential to be created. | Yes | string | -| domain | query | Is the identifier of the domain in which the credential is to be created. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | -| summary | query | Is the summary text for the credential. | No | string | -| kind | query | The type of credential to create. Must be one of - encrypted The username and password are held encrypted in the database. vars The username and password contain variable names to be expanded when the credential is used. Held unencrypted in the database. ppk Public/Private Key file. dfo DFO filename for use with Harvest. | No | string | -| username | query | Required for credentials of kind encrypted, vars or ppk. The username to be stored against the credential. | No | string | -| password | query | Required for credentials of kind encrypted and vars. The password to be stored against the credential. | No | string | -| keyfile | query | Required for credentials of kind ppk. The path of the private keyfile to be used by the credential. | No | string | -| filename | query | Required for credentials of kind dfo. The path of the Harvest DFO file containing the encrypted username/password. | No | string | - -##### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/restapi/models/#success) | - -### /dmadminweb/API/mod/credential/{cred_id} +| cred_id | path | Is the name of the _Credential_ to be created. | Yes | string | +| domain | query | Is the identifier of the _Domain_ in which the _Credential_ is to be created. Either its name, its qualified name with its parent _Domains_ included in dot notation (i.e. GLOBAL.Product) or its internal ID. | Yes | string | +| summary | query | Is the summary text for the _Credential_. | No | string | +| kind | query | The type of _Credential_ to create. Must be one of -
  • encrypted - The username and password are held encrypted in the database.
  • vars - The username and password contain variable names to be expanded when the _Credential_ is used. Held un-encrypted in the database.
  • ppk - Public/Private Key file.
  • dfo- DFO filename for use with CA Harvest.
    • | No | string | +| username | query | Required for _Credential_ of kind encrypted, vars or ppk. The username to be stored against the _Credential_. | No | string | +| password | query | Required for _Credential_ of kind encrypted and vars. The password to be stored against the credential. | No | string | +| keyfile | query | Required for _Credential_ of kind ppk. The path of the private keyfile to be used by the _Credential_. | No | string | +| filename | query | Required for _Credential_ of kind dfo. The path of the Harvest DFO file containing the encrypted username/password. | No | string | -#### GET +{{% include "userguide/reusable/Model Success.md" %}} -##### Summary +## Modify a _Credential_ -Modify a Credential +This call modifies an existing _Credential_. The attributes of the _Credential_ are modified through parameters to the API. -##### Description +**REST Api Endpoint** -This call modifies an existing credential. The attributes of the credential are modified through parameters to the API. +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/new/credential/{cred_id} | -It is not possible to modify the credential's kind (encrypted, vars, dfo or ppk) once it has been created. If you need to change the kind of the credential you must delete it and recreate it. - -##### Parameters +**Parameters** | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | -| cred_id | path | Is the ID of the credential to be modified. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | -| domain | query | Is the identifier of the domain in which the credential is to be created. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | -| summary | query | Is the summary text for the credential. | No | string | -| kind | query | The type of credential to create. Must be one of - encrypted The username and password are held encrypted in the database. vars The username and password contain variable names to be expanded when the credential is used. Held unencrypted in the database. ppk Public/Private Key file. dfo DFO filename for use with Harvest. | No | string | -| username | query | Required for credentials of kind encrypted, vars or ppk. The username to be stored against the credential. | No | string | -| password | query | Required for credentials of kind encrypted and vars. The password to be stored against the credential. | No | string | -| keyfile | query | Required for credentials of kind ppk. The path of the private keyfile to be used by the credential. | No | string | -| filename | query | Required for credentials of kind dfo. The path of the Harvest DFO file containing the encrypted username/password. | No | string | - -##### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/restapi/models/#success) | +| cred_id | path | Is the ID of the _Credential_ to be modified. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | +| domain | query | Is the identifier of the _Domain_ in which the _Credential_ is to be created. Either its name, its qualified name with its parent _Domains_ included in dot notation (i.e. GLOBAL.Products) or its internal ID. | Yes | string | +| summary | query | Is the summary text for the _Credential_. | No | string | +| kind | query | The type of _Credential_ to create. Must be one of -
  • encrypted - The username and password are held encrypted in the database.
  • vars - The username and password contain variable names to be expanded when the _Credential_ is used. Held un-encrypted in the database.
  • ppk - Public/Private Key file.
  • dfo- DFO filename for use with CA Harvest.
    • | No | string | +| username | query | Required for _Credential_ of kind encrypted, vars or ppk. The username to be stored against the credential. | No | string | +| password | query | Required for _Credential_ of kind encrypted and vars. The password to be stored against the credential. | No | string | +| keyfile | query | Required for _Credential_ of kind ppk. The path of the private keyfile to be used by the credential. | No | string | +| filename | query | Required for _Credential_ of kind dfo. The path of the Harvest DFO file containing the encrypted username/password. | No | string | -### /dmadminweb/API/del/credential/{cred_id} +{{% include "userguide/reusable/Model Success.md" %}} -#### GET +## Deleting a Credential -##### Summary +This call deletes a _Credential_. -Deleting a Credential +**REST Api Endpoint** -##### Description +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/del/credential/{cred_id} | -This call deletes a credential. - -##### Parameters +**Parameters** | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | -| cred_id | path | Is the ID of the credential to be deleted. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | - -##### Responses +| cred_id | path | Is the ID of the _Credential_ to be deleted. Either its name, its qualified name with its parent _Domain_ included in dot notation (i.e. GLOBAL.Products) or its internal ID. | Yes | string | -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/restapi/models/#success) | +{{% include "userguide/reusable/Model Success.md" %}} diff --git a/content/en/userguide/restapi/deployment-log.md b/content/en/userguide/restapi/deployment-log.md index a06d2439..6e773995 100644 --- a/content/en/userguide/restapi/deployment-log.md +++ b/content/en/userguide/restapi/deployment-log.md @@ -1,31 +1,24 @@ --- title: "Deployment Log" linkTitle: "Deployment Log" -weight: 60 +weight: 22 description: > Retrieve a deployment log. --- -### /dmadminweb/API/log/{lognumber} +Retrieve deployment log. This call returns a JSON object representing the specified deployment log. -#### GET +**REST Api Endpoint** -##### Summary +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/log/{lognumber} | -Retrieve deployment log - -##### Description - -This call returns a JSON object representing the specified deployment log. - -##### Parameters +**Parameters** | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | -| lognumber | path | Is the deployment ID being retrieved. Note if the deployment log relates to an application outside of your domain hierarchy or to an application to which you do not have read access then you will receive an error. | Yes | integer | - -##### Responses +| lognumber | path | Is the deployment ID being retrieved. Note if the deployment log relates to an _Application_ outside of your _Domain_ access or to an _Application_ to which you do not have read access, then you will receive an error. | Yes | integer | -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [log_result](/restapi/models/#log_result) | +{{% include "userguide/reusable/Model Deployment Log Result.md" %}} +{{% include "userguide/reusable/Model Deployment Log.md" %}} diff --git a/content/en/userguide/restapi/deployment.md b/content/en/userguide/restapi/deployment.md index e260f403..617312b0 100644 --- a/content/en/userguide/restapi/deployment.md +++ b/content/en/userguide/restapi/deployment.md @@ -1,40 +1,33 @@ --- title: "Deployment" linkTitle: "Deployment" -weight: 50 +weight: 20 description: > Start a deployment for a specified Application --- -### /dmadminweb/API/deploy/{app_id}/{env_id} +## Start Deployment -#### GET +This call starts a deployment of the specified _Application_ into the specified _Environment_. -##### Summary +In order for API deployments to work through the permission model, there has to be a Deploy task either in the _Domain_ in which the specified _Application_ is located or in any of the parent _Domains_ if the Deploy task is set to be available to _Sub-domains_. This mechanism ensures that the invoking user has permission to deploy the _Application_ (since the permissions are checked against 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. -Start Deployment +Note - Any additional parameters are created as Global Variables accessible with a url_prefix. For example, if you passed "myparam=123" as a parameter in the "deploy" api call, it would be available as $url_myparam. -##### Description +**REST Api Endpoint** -This call starts a deployment of the specified _Application_ into the specified environment. +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/deploy/{app_id}/{env_id} | -In order for API deployments to work through the permission model, there has to be a Deploy task either in the domain in which the specified application is located or in any of the parent domains if the Deploy task is set to be available to sub-domains. If finer control is required, the task can be named via the task parameter. - -This mechanism ensures that the invoking user has permission to deploy the application (since the permissions are checked against 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. - -Note - Any additional parameters are created as Global Variables accessible with a url_prefix. For example, if you passed "myparam=123" as a parameter in the "deploy" api call, it would be available as $url_myparam in DeployHub. - -##### Parameters +**Parameters** | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | | wait | query | If the wait parameter is not specified - or is specified and set to Y - then the call does not return until the deployment is complete. If the wait parameter is set to N then the call returns as soon as the deployment has been instigated but before it completes. In both cases, the deployment id is returned. | No | string | -| task | query | Is the identifier of a Deploy task to execute in order to perform the deployment. Either its name, its qualified name (i.e. with its domain and any parent domain(s) included in dot notation) or its internal ID. If the task is not specified, the first accessible Deploy task within the application's domain is used (or any Deploy task in parent domains if they are set to be available to sub-domains). | No | string | -| app_id | path | Is the identifier of an application. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | -| env_id | path | Is the identifier of an environment. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | +| task | query | Is the identifier of a Deploy task to execute in order to perform the deployment. 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 Deploy Task within the _Application's_ _Domain_ is used (or any Deploy Task in parent _Domain_ if they are set to be "available" to _Sub-domains). | No | string | +| app_id | path | Is the identifier of an _Application_. Either its name, its qualified name with its parent _Domain included in dot notation (i.e. GLOBAL.Product) or its internal ID. | Yes | string | +| env_id | path | Is the identifier of an _Environment_. Either its name, its qualified name with its parent _Domains_ included in dot notation (i.e. GLOBAL.Product) or its internal ID. | Yes | string | -##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [deployment_result](/restapi/models/#deployment_result) | +{{% include "userguide/reusable/Model Deployment Result.md" %}} \ No newline at end of file diff --git a/content/en/userguide/restapi/endpoints.md b/content/en/userguide/restapi/endpoints.md index 28ecda5a..a4ad6280 100644 --- a/content/en/userguide/restapi/endpoints.md +++ b/content/en/userguide/restapi/endpoints.md @@ -1,112 +1,94 @@ --- -title: "End Points" -linkTitle: "End Points" -weight: 40 +title: "Endpoint APIs" +linkTitle: "Endpoint APIs" +weight: 24 description: > - Get a list of Endpoints. + APIs for retrieving and updating Endpoints.. --- -### /dmadminweb/API/servers +## Get a List of _EndPoints_ -#### GET +This call returns an array of JSON objects representing each _Endpoint_ to which the logged-in _User_ has access. -##### Summary +If the all parameter is not specified then only the _Endpoint_ associated with the _User's_ home _Domain_ are listed. If the "all" parameter is specified and is set to "y", for Yes, then the result includes the _Applications_ included in any accessible _Sub-domains. -List All Accessible Endpoints +**REST Api Endpoint** -##### Description +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/servers | -This call returns an array of JSON objects representing each application to which the logged-in user has access. - -If the all parameter is not specified then only the applications associated with the user's home domain are listed. If the all parameter is specified and is set to "y" then the result includes the applications included in any accessible sub-domains. - -##### Parameters +**Parameters** | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | | all | query | y or n | No | string | -##### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [servers_result](/restapi/models/#servers_result) | -### /dmadminweb/API/server/{identifier} +{{% include "userguide/reusable/Model Endpoints Result.md" %}} +{{% include "userguide/reusable/Model Endpoints.md" %}} -#### GET +## Retrieve Specific _Endpoint_ -##### Summary +This call returns a JSON object representing the specified _Endpoint_. -Retrieve specific server +**REST Api Endpoint** -##### Description +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/server/{identifier} | -This call returns a JSON object representing the specified server. -##### Parameters +**Parameters** | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | -| identifier | path | Is the identifier of the server. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | - -##### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [server_result](/restapi/models/#server_result) | - -### /dmadminweb/API/assign/server/{server_id}/{env_id} +| identifier | path | Is the identifier of the _Endpoint_. Either its name, its qualified name with its parent _Domains_ included in dot notation (i.e. GLOBLAL.Product) or its internal ID. | Yes | string | -#### GET +{{% include "userguide/reusable/Model Endpoint Result.md" %}} +{{% include "userguide/reusable/Model Endpoints.md" %}} -##### Summary +##Assign an _Endpoint_ to an _Environment_** -Assign a Server to an Environment +This call allows an existing _Endpoint_ to be associated with an existing _Environment_. Once the _Endpoint_ is associated with an _Environment_ it can receive _Components_ during a deployment. -##### Description +_Endpoint_ can be associated with more than one _Environment_. Assigning an _Endpoint_ to an _Environment_ will not disassociate the _Endpoint_ from any other _Environment_ with which it may be already associated. To move an _Endpoint_ between _Environments_ see the "Disassociate an _Endpoint_ from and _Environment_" below to remove the _Endpoint_ from the original _Environment_. -This call allows an existing server to be associated with an existing environment. Once the server is associated with an environment it can receive components during a deployment. +**REST Api Endpoint** -Servers can be associated with more than one environment. Assigning a server to an environment will not disassociate the server from any other environment with which it may be already associated. To move a server between environments you must use the API/server/unassign call to remove the server from the original environment - see next section for more information. +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/assign/server/{server_id}/{env_id} | ##### Parameters | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | -| server_id | path | Is the identifier of the server to be assigned. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) 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 (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | +| server_id | path | Is the identifier of the _Endpoint_ 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 | -##### Responses +{{% include "userguide/reusable/Model Success.md" %}} -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/restapi/models/#success) | +## Disassociate a _Endpoint_ from an _Environment_ -### /dmadminweb/API/unassign/server/{server_id}/{env_id} - -#### GET - -##### Summary - -Disassociate a Server from an Environment - -##### Description +**Description** This call disassociates a server from an environment. When the server is disassociated from the environment then any subsequent deployments to that environment will not result in any files or operations being directed at the server. This call does not delete the server - it simply disassociates it from the environment. To delete a server use the API/del/server call. -##### Parameters +**REST Api Endpoint** + +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/unassign/server/{server_id}/{env_id} + +**Parameters** | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | -| server_id | path | Is the identifier of the server to be assigned. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) 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 (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | - -##### Responses +| server_id | path | Is the identifier of the _Endpoint_ to be assigned. Either its name, its qualified name 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 (GLOBAL.Product) or its internal ID. | Yes | string | -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/restapi/models/#success) | +{{% include "userguide/reusable/Model Success.md" %}} diff --git a/content/en/userguide/restapi/environments.md b/content/en/userguide/restapi/environments.md index 73eb367a..a4554875 100644 --- a/content/en/userguide/restapi/environments.md +++ b/content/en/userguide/restapi/environments.md @@ -1,58 +1,52 @@ --- title: "Environments" linkTitle: "Environments" -weight: 30 +weight: 26 description: > Get a list of Environments. --- -### /dmadminweb/API/environments -#### GET -##### Summary +## List Environments -List Environments +**Description** -##### Description +This call returns an array of JSON objects representing each _Environment_ to +which the logged-in _User_ has access. -This call returns an array of JSON objects representing each environment to -which the logged-in user has access. +If the all parameter is not specified then only the _Environments_ associated with the _User's_ home _Domain_ are listed. If the all parameter is specified and is set to "y", for yes, then the result includes the _Environments_ included in any accessible _Sub-domains_. -If the all parameter is not specified then only the environments associated with the user's home domain are listed. If the all parameter is specified and is set to "y" then the result includes the environments included in any accessible sub- domains. +**REST Api Endpoint** -##### Parameters +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/environments | + +**Parameters** | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | | all | query | y or n | No | string | -##### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [environments_result](/restapi/models/#environments_result) | - -### /dmadminweb/API/environment/{identifier} +{{% include "userguide/reusable/Model Environments Result.md" %}} +{{% include "userguide/reusable/Model Environment.md" %}} -#### GET +## Retrieve specific _Environment_ -##### Summary +This call returns a JSON object representing the specified _Environment_. -Retrieve specific environment +**REST Api Endpoint** -##### Description +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/environment/{identifier} -This call returns a JSON object representing the specified environment. - -##### Parameters +**Parameters** | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | -| identifier | path | Is the identifier of the environment. Either its name, its qualified name i.e. with its parent domains included in dot notations or its internal ID. | Yes | string | - -##### Responses +| identifier | path | Is the identifier of the _Environment_. Either its name, its qualified name with its parent _Domains_ included in dot notations (i.e. GLOBAL.Product) or its internal ID. | Yes | string | -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [environment_result](/restapi/models/#environment_result) | +{{% include "userguide/reusable/Model Success.md" %}} +{{% include "userguide/reusable/Model Environments Result.md" %}} \ No newline at end of file diff --git a/content/en/userguide/restapi/login.md b/content/en/userguide/restapi/login.md deleted file mode 100644 index 629523a0..00000000 --- a/content/en/userguide/restapi/login.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "Login" -linkTitle: "Login" -weight: 5 -description: > - Login into DeployHub. ---- - -### /dmadminweb/API/login - -#### GET - -##### Summary - -Login - -##### Description - -When issuing calls to the API, the client application must either first issue a "login" call, specifying the username and password or must specify the username and password in each individual call to the API. - -When calling the API from inside DMScript (the built-in scripting language), the JSESSIONID value for the logged-in user is available via a global variable ($JSESSIONID). This can be used to allow DMScript to call the API without the need for an explicit second login. See the DMScript user guide for more information. - -##### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| user | query | User Id | Yes | string | -| pass | query | Password for User | Yes | string | - -##### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | The result will include a JSESSIONID cookie. Include this in subsequent calls to the API. | [success](/restapi/models/#success) | diff --git a/content/en/userguide/restapi/models.md b/content/en/userguide/restapi/models.md deleted file mode 100644 index e78a1df9..00000000 --- a/content/en/userguide/restapi/models.md +++ /dev/null @@ -1,329 +0,0 @@ ---- -title: "Models" -linkTitle: "Models" -weight: 110 -description: > - Using RESTful API's to Integrate DeployHub into DevOps Tooling. ---- - -#### Application - -| 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 BASE application. | No | -| name | string | The name of the BASE application. | No | -| predecessorid | integer | The ID of the previous application version if the application is a version. | No | -| versionid | integer | The ID of the application version if the application is a version. | No | -| versionname | string | The name of the application version if the application is a version. | No | - - - -#### Environment - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| domain | string | The fully-qualified domain name of the domain in which the environment is located. | No | -| id | integer | Is the internal ID of the environment | No | -| name | string | Is the name of the environment | No | -| owneruser | string | If the "owner" of the environment is a user, then this is the name of the user | No | -| ownergroup | string | If the "owner" of the environment is a user group, then this is the name of that group. | No | -| summary | string | The summary string associated with the environment. | No | -| applications | [applications](/userguide/restapi/models/#applications) | | No | - - - -#### Environments_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 | [ [environments](/restapi/models/#environments) ] | Is a JSON array of objects, one for each environment returned by the query (if success is true). | No | - - -#### environment_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 | [environment](/restapi/models/#environment) | | 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 | - -#### application_version - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| id | integer | Is the internal application ID | No | -| name | string | Is the name of the application version | No | -| summary | string | Is the summary text associated with the application version | No | - -#### application_predecessor - -Only returned for application versions. A JSON Object representing the predecessor of this application (if the application is a version). - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| id | integer | Is the internal application ID | No | -| name | string | Is the name of the predecessor application | No | -| summary | string | Is the summary text associated with the predecessor application | No | -| versions | [ [application_version](/restapi/models/#application_version) ] | | No | - -#### component - -| 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 application is located. | No | -| application_id | string | Is the internal ID of the application | No | -| application_name | string | Is the name of the application | No | -| owneruser | string | If the "owner" of the application is a user, then this is the name of the useron | No | -| ownergroup | string | If the "owner" of the application is a user group, then this is the name of that group. | No | -| predecessor | [application_predecessor](/restapi/models/#application_predecessor) | | No | - -#### approval - -| 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 - -| 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 | - -#### application_version_full - -Is a JSON object representing the application being retrieved. - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| approvals | [ [approval](/restapi/models/#approval) ] | | No | -| rejections | [ [rejection](/restapi/models/#rejection) ] | | 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](/restapi/models/#component) ] | | No | -| requests | [ [request](/restapi/models/#request) ] | | No | -| application_versions | [ [application_version](/restapi/models/#application_version) ] | | No | - -#### application_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 | [application_version_full](/restapi/models/#application_version_full) | | No | - -#### server - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| automd5 | string | Is a Boolean representing if "Auto MD5 Scanning" is set for the server. | No | -| autoping | string | Is a Boolean representing if "Auto Ping" is set for the server. | No | -| basedir | string | Is the base directory for the server. | No | -| comptypes | [ [comptype](/restapi/models/#comptype) ] | | No | -| credential | string | Is the name of the credential used to connect to the server. | No | -| domain | string | Is the server's fully qualified domain. | No | -| environments | [ [environment](/restapi/models/#environment) ] | | No | -| hostname | string | Is the hostname of the server | No | -| id | string | Is the server's internal object ID. | No | -| md5template | string | Is the name of the template to be used for notification should the server fail an automated mD5 scan. | No | -| name | string | Is the server's name. | No | -| owneruser | string | If the "owner" of the server is a user, then this is the name of the user | No | -| ownergroup | string | If the "owner" of the server is a user group, then this is the name of that group. | No | -| pingend | string | The time after which auto ping will stop (in format HH:MM) | No | -| pingstart | string | The time at which auto ping will start (in format HH:MM) | No | -| pingtemplate | string | Is the name of the template to be used for notification should the server fail an automated ping. | No | -| protocol | string | The protocol used to connect to the server. | No | -| summary | string | Any summary text associated with the server. | No | - -#### comptype - -component type used by components and servers - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| comptype | string | component type used by components and servers | | - -#### servers - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| servers | array | | | - -#### servers_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 | [servers](/restapi/models/#servers) | | No | - -#### server_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 | [server](/restapi/models/#server) | | No | - -#### component_version - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| id | integer | Is the internal application ID | No | -| name | string | Is the name of the application version | No | -| summary | string | Is the summary text associated with the application version | No | - -#### component_predecessor - -Only returned for application versions. A JSON Object representing the predecessor of this application (if the application is a version). - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| id | integer | Is the internal application ID | No | -| name | string | Is the name of the predecessor application | No | -| summary | string | Is the summary text associated with the predecessor application | No | -| versions | [ [component_version](/restapi/models/#component_version) ] | | 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_full](/restapi/models/#component_version_full) | | No | - -#### component_version_full - -Is a JSON object representing the application being retrieved. - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| branch | string | Is the name of the branch on which this component is located (if a component version). 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 server is a user, then this is the name of the user | No | -| ownergroup | string | If the "owner" of the server is a user group, then this is the name of that group. | No | -| requests | [ [request](/restapi/models/#request) ] | | No | -| summary | string | Is the summary text associated with the component version | No | -| component_versions | [ [component_version](/restapi/models/#component_version) ] | | No | -| applications | [ [application_version_full](/restapi/models/#application_version_full) ] | | No | -| predecessor | [ [component_predecessor](/restapi/models/#component_predecessor) ] | | No | - -#### event_timestamp - -datetime and epoc - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| datetime | string | is the date/time in YYYY:MM:DD:hh:mm format | No | -| timestamp | integer | is the date/time in Epoch Time. | No | - -#### event_creator - -Is an object representing the user who created the event - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| id | integer | is the internal user id | No | -| name | string | is the name of the user. | No | - -#### event_environment - -Is an object representing the user who created the event - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| id | integer | is the internal environment ID | No | -| name | string | is the environment name. | No | - -#### event - -Calendar Event - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| allday | boolean | Is a Boolean indicating whether the event is an "all day" event. | No | -| application | [application](/restapi/models/#application) | | No | -| created | [event_timestamp](/restapi/models/#event_timestamp) | | No | -| creator | [event_creator](/restapi/models/#event_creator) | | No | -| endtime | [event_timestamp](/restapi/models/#event_timestamp) | | No | -| deployid | integer | Is the ID of the deployment (if this is a deployment record), 0 otherwise. | No | -| desc | string | Is the Description of the event. | No | -| environment | [event_environment](/restapi/models/#event_environment) | | No | -| id | integer | Is the internal event id. | No | -| pending | boolean | Is a Boolean indicating whether the event is awaiting approval by the environment owner. | No | -| starttime | [event_timestamp](/restapi/models/#event_timestamp) | | No | -| title | string | Is the event title. | No | -| type | string | Is the event type. | No | - -#### calendar_event_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 | [ [event](/restapi/models/#event) ] | | No | - -#### deployment_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 | -| deploymentid | integer | Deployment Id | No | - -#### log - -Deployment Log - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| application | string | The name of the application that was deployed. | No | -| complete | boolean | A Boolean indicating if the deployment is complete (true) or still in progress (false). | No | -| environment | string | The environment to which the application was deployed. | No | -| exitcode | integer | The exit code of the deployment. | No | -| exitstatus | string | The error text if the deployment failed. | No | -| started | integer | The start date/time of the deployment (in Epoch time) | No | -| finished | integer | The end date/time of the deployment (in Epoch time) | No | -| id | integer | The deployment ID. | No | -| loglinecount | integer | The number of lines in the "logoutput" array | No | -| logoutput | [ string ] | | No | - -#### log_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 | [log](/restapi/models/#log) | | No | - -#### attribute - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| attrname | string | name of the attribute key | No | -| attrvalue | string | value for the attribute | No | - -#### attribute_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 | -| attributes | [ [attribute](/restapi/models/#attribute) ] | | No | diff --git a/content/en/userguide/restapi/users.md b/content/en/userguide/restapi/users.md index 211abaeb..664a55d8 100644 --- a/content/en/userguide/restapi/users.md +++ b/content/en/userguide/restapi/users.md @@ -1,58 +1,46 @@ --- -title: "Users" -linkTitle: "Users" +title: "User APIs" +linkTitle: "User APIs" weight: 20 description: > Associate a User to a User Group (Pro Feature). --- -### /dmadminweb/API/assign/user/{user_id}/{group_id} +## Associate a User with a User Group -#### GET +This call assigns an existing _User_ to a _Group_. Once a user has been assigned to the group then the _User_ will have access to any object to which the _Group_ has been granted appropriate access. -##### Summary +**REST Api Endpoint** -Associate a User with a User Group +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/assign/user/{user_id}/{group_id} | -##### Description - -This call assigns an existing user to a User Group. Once a user has been assigned to the group then the user will have access to any object to which the User Group has been granted appropriate access. - -##### Parameters +**Parameters** | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | -| user_id | path | Is the identifier of the user to be assigned. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | integer | -| group_id | path | Is the identifier of the User Group to which the user should be assigned. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | - -##### Responses +| user_id | path | Is the identifier of the _User_ 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 | +| group_id | path | Is the identifier of the _Group_ to which the _User_ should be assigned. Either its name, with its parent _Domains_ included in dot notation (i.e. GLOBAL.Product) or its internal ID. | Yes | string | -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/restapi/models/#success) | +{{% include "userguide/reusable/Model Success.md" %}} -### /dmadminweb/API/unassign/user/{user_id}/{group_id} +## Disassociate a User from a User Group -#### GET +This call disassociates a _User_ from a _Group_. Once a _User_ has been removed from the _Group_ they no longer have access to any object to which access has been granted through the _Group_. -##### Summary +**REST Api Endpoint** -Disassociate a User from a User Group - -##### Description - -This call disassociates a user from a User Group. Once a user has been removed from the group they no longer have access to any object to which access has been granted through the User Group. +| HTTP Verb | URL | +| ---- | ----------- | +| GET | /dmadminweb/API/unassign/user/{user_id}/{group_id} | ##### Parameters | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ---- | -| user_id | path | Is the identifier of the user to be assigned. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | integer | -| group_id | path | Is the identifier of the User Group to which the user should be assigned. Either its name, its qualified name (i.e. with its parent domain(s) included in dot notation) or its internal ID. | Yes | string | - -##### Responses +| user_id | path | Is the identifier of the _User_ 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 | +| group_id | path | Is the identifier of the _Group_ to which the _User_ should be assigned. Either its qualified name with its parent _Domains_ included in dot notation (i.e. GLOBAL.Product) or its internal ID. | Yes | string | -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success or failure. Check success field for status. | [success](/restapi/models/#success) | +{{% include "userguide/reusable/Model Success.md" %}} diff --git a/content/en/userguide/reusable/Model Application Result.md b/content/en/userguide/reusable/Model Application Result.md index 20b0bf17..a8e4cc18 100644 --- a/content/en/userguide/reusable/Model Application Result.md +++ b/content/en/userguide/reusable/Model Application Result.md @@ -1,7 +1,7 @@ -**Response for Applications** +**_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 returned instead. | No | -| result | An array of _Application_ Objects. | Is a JSON array of objects, one for each environment returned by the query (if success is true). | 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 | diff --git a/content/en/userguide/reusable/Model Application Version Full.md b/content/en/userguide/reusable/Model Application Version Full.md index a1f265d5..42a751bc 100644 --- a/content/en/userguide/reusable/Model Application Version Full.md +++ b/content/en/userguide/reusable/Model Application Version Full.md @@ -1,11 +1,11 @@ -**Responses for _Application Version_ Results Full Detail** +**_Application Version_ Results Full Detail** | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | -| approvals | [ An Array of Approvals | | No | -| rejections | [ An Array of Rejections ] | | No | -| summary | string | Is the summary text associated with the application | No | +| 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](/restapi/models/#component) ] | | No | -| requests | [ [request](/restapi/models/#request) ] | | No | -| application_versions | Arry of Related _Application Versions_ | | No | \ No newline at end of file +| components | _Component_ | See Component Object. | No | +| requests | request | See Request Object. | No | +| application_versions | Arry of Related _Application Versions_ | See _Application_ Object. | No | \ No newline at end of file diff --git a/content/en/userguide/reusable/Model Application Version Result.md b/content/en/userguide/reusable/Model Application Version Result.md index af2bbb53..de90ec5f 100644 --- a/content/en/userguide/reusable/Model Application Version Result.md +++ b/content/en/userguide/reusable/Model Application Version Result.md @@ -1,37 +1,6 @@ -**Responses for _Application Version_ Result** +**_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_| | No | - -**_Application Version_ Results Full Detail** - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| approvals | [ An Array of Approvals | | No | -| rejections | [ An Array of Rejections ] | | 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](/restapi/models/#component) ] | | No | -| requests | [ [request](/restapi/models/#request) ] | | No | -| application_versions | Arry of Related _Application Versions_ | | 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 | - +| result | An array of _Application Versions_ (see below). | JSON array of _Application Versions_ | No | diff --git a/content/en/userguide/reusable/Model Application Version.md b/content/en/userguide/reusable/Model Application Version.md index 55e81883..b463c6e6 100644 --- a/content/en/userguide/reusable/Model Application Version.md +++ b/content/en/userguide/reusable/Model Application Version.md @@ -1,4 +1,4 @@ -**Responses for _Application Version_** +**_Application Version_ Object** | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | diff --git a/content/en/userguide/reusable/Model Approve or Reject.md b/content/en/userguide/reusable/Model Approve or Reject.md index 32fb2845..74e29bff 100644 --- a/content/en/userguide/reusable/Model Approve or Reject.md +++ b/content/en/userguide/reusable/Model Approve or Reject.md @@ -1,17 +1,17 @@ -**Responses for Approval Results** +**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 | +| 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 | -**Responses for Rejection Results** +**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 | +| 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 | diff --git a/content/en/userguide/reusable/Model Component Predecessor.md b/content/en/userguide/reusable/Model Component Predecessor.md index 1e7c366d..138f413c 100644 --- a/content/en/userguide/reusable/Model Component Predecessor.md +++ b/content/en/userguide/reusable/Model Component Predecessor.md @@ -1,4 +1,4 @@ -**Responses for _Component_ Predecessor** +**_Component_ Predecessor** Only returned for _Component Versions_. A JSON Object representing the predecessor of this _Component_. @@ -7,4 +7,4 @@ Only returned for _Component Versions_. A JSON Object representing the predecess | 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](/restapi/models/#component_version) ] | | No | \ No newline at end of file +| versions | _Component Version_ | A JSON Object representing the parent _Component Version_ of this _Component_. | No | diff --git a/content/en/userguide/reusable/Model Component Result.md b/content/en/userguide/reusable/Model Component Result.md new file mode 100644 index 00000000..f526a630 --- /dev/null +++ b/content/en/userguide/reusable/Model Component Result.md @@ -0,0 +1,6 @@ +**_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 | \ No newline at end of file diff --git a/content/en/userguide/reusable/Model Component Version Full.md b/content/en/userguide/reusable/Model Component Version Full.md index 76916176..60d142fb 100644 --- a/content/en/userguide/reusable/Model Component Version Full.md +++ b/content/en/userguide/reusable/Model Component Version Full.md @@ -1,4 +1,4 @@ -**Responses for_Component Version_ Full Detail** +**_Component Version_ Full Detail** Is a JSON object representing the _Component_ being retrieved. @@ -11,8 +11,8 @@ Is a JSON object representing the _Component_ being retrieved. | 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](/restapi/models/#request) ] | | No | -| summary | string | Is the summary text associated with the _Component Version_ | No | -| component_versions | [ [component_version](/restapi/models/#component_version) ] | | No | -| applications | [ [application_version_full](/restapi/models/#application_version_full) ] | | No | -| predecessor | [ [component_predecessor](/restapi/models/#component_predecessor) ] | | No | \ No newline at end of file +| 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 | diff --git a/content/en/userguide/reusable/Model Component Version Result.md b/content/en/userguide/reusable/Model Component Version Result.md index b4c7b832..2ce308f5 100644 --- a/content/en/userguide/reusable/Model Component Version Result.md +++ b/content/en/userguide/reusable/Model Component Version Result.md @@ -1,6 +1,6 @@ -**Responses for _Component Version_ Result** +**_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_full](/restapi/models/#component_version_full) | | No | +| result | _Component Version_ with details. | Full details for a specific _Component Version_. | No | diff --git a/content/en/userguide/reusable/Model Component.md b/content/en/userguide/reusable/Model Component.md index a33ff7e9..8869593e 100644 --- a/content/en/userguide/reusable/Model Component.md +++ b/content/en/userguide/reusable/Model Component.md @@ -1,16 +1,15 @@ -*_Component_ Object for APIs** +**_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 application is located. | No | -| application_id | string | Is the internal ID of the _Application_ | No | -| application_name | string | Is the name of the _Application_ | No | -| owneruser | string | If the "owner" of the _Application_ is a user, then this is the name of the useron | No | -| ownergroup | string | If the "owner" of the _Application_ is a _User Group_, then this is the name of that _Group_. | No | -| predecessor | _Application Version_ | Parent _Application Version_. | No | +| 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 | -[application_predecessor](/restapi/models/#application_predecessor) \ No newline at end of file diff --git a/content/en/userguide/reusable/Model Deployment Log Result.md b/content/en/userguide/reusable/Model Deployment Log Result.md index bec67b03..39936b89 100644 --- a/content/en/userguide/reusable/Model Deployment Log Result.md +++ b/content/en/userguide/reusable/Model Deployment Log Result.md @@ -1,6 +1,6 @@ -**Responses for Deployment Log Result** +**Deployment Log 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 | [log](/restapi/models/#log) | | No | +| result | log | The Deployment Log.| No | diff --git a/content/en/userguide/reusable/Model Deployment Log.md b/content/en/userguide/reusable/Model Deployment Log.md index bd98f2f1..13b273ca 100644 --- a/content/en/userguide/reusable/Model Deployment Log.md +++ b/content/en/userguide/reusable/Model Deployment Log.md @@ -1,4 +1,4 @@ -**Responses for Deployment Log** +**Deployment Log** | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | @@ -7,8 +7,8 @@ | environment | string | The _Environment_ to which the _Application_ was deployed. | No | | exitcode | integer | The exit code of the deployment. | No | | exitstatus | string | The error text if the deployment failed. | No | -| started | integer | The start date/time of the deployment (in Epoch time) | No | -| finished | integer | The end date/time of the deployment (in Epoch time) | No | +| started | integer | The start date/time of the deployment (in Epoch time). | No | +| finished | integer | The end date/time of the deployment (in Epoch time). | No | | id | integer | The deployment ID. | No | -| loglinecount | integer | The number of lines in the "logoutput" array | No | -| logoutput | [ string ] | | No | \ No newline at end of file +| loglinecount | integer | The number of lines in the "logoutput" array. | No | +| logoutput | [ string ] | The log output.| No | \ No newline at end of file diff --git a/content/en/userguide/reusable/Model Deployment Result.md b/content/en/userguide/reusable/Model Deployment Result.md index b48c38f6..fda3fb77 100644 --- a/content/en/userguide/reusable/Model Deployment Result.md +++ b/content/en/userguide/reusable/Model Deployment Result.md @@ -1,4 +1,4 @@ -**Responses for Deployment Result** +**Deployment Result** | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | diff --git a/content/en/userguide/reusable/Model Endpoints.md b/content/en/userguide/reusable/Model Endpoints.md index 61f4fcff..05ef0cb6 100644 --- a/content/en/userguide/reusable/Model Endpoints.md +++ b/content/en/userguide/reusable/Model Endpoints.md @@ -1,4 +1,4 @@ -**_Endpoint_ Object for APIs ** +**_Endpoint_ Object** | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | diff --git a/content/en/userguide/reusable/Model Environment Result.md b/content/en/userguide/reusable/Model Environment Result.md index c53d1a69..8f46c3b5 100644 --- a/content/en/userguide/reusable/Model Environment Result.md +++ b/content/en/userguide/reusable/Model Environment Result.md @@ -3,4 +3,4 @@ | 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 | [environment](/restapi/models/#environment) | | No | \ No newline at end of file +| result | _Environment_ Object | An _Environment_.| No | \ No newline at end of file diff --git a/content/en/userguide/reusable/Model Environment.md b/content/en/userguide/reusable/Model Environment.md index 25c35e25..46fb9d3d 100644 --- a/content/en/userguide/reusable/Model Environment.md +++ b/content/en/userguide/reusable/Model Environment.md @@ -1,11 +1,11 @@ -**_Environment_ Object for APIs** +**_Environment_ Object** | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | domain | string | The fully-qualified _Domain_ Name of the _Domain_ in which the _Environment_ is located. | No | | id | integer | Is the internal ID of the _Environment_. | No | -| name | string | Is the name of the _Environment_ | No | +| name | string | Is the name of the _Environment_. | No | | owneruser | string | If the "owner" of the _Environment_ is a _User_, then this is the name of the _User_. | No | | ownergroup | string | If the "owner" of the _Environment_ is a _Group_, then this is the name of that _Group_. | No | | summary | string | The summary string associated with the environment. | No | -| applications | [applications](/userguide/restapi/models/#applications) | | No | \ No newline at end of file +| applications | An _Application_ Object | The _Application_. | No | \ No newline at end of file diff --git a/content/en/userguide/reusable/Model Environments Result.md b/content/en/userguide/reusable/Model Environments Result.md index 800a4c75..50d8f772 100644 --- a/content/en/userguide/reusable/Model Environments Result.md +++ b/content/en/userguide/reusable/Model Environments Result.md @@ -1,6 +1,6 @@ -**Responses for _Environments_ Result** +**_Environments_ 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 | [ An Array of _Environments_ ] | Is a JSON array of objects, one for each _Environment_ returned by the query (if success is true). | No | \ No newline at end of file +| result | An Array of _Environments_ | Is a JSON array of objects, one for each _Environment_ returned by the query (if success is true). | No | \ No newline at end of file diff --git a/content/en/userguide/reusable/Model Request.md b/content/en/userguide/reusable/Model Request.md index 7fb3d60a..6618e1ac 100644 --- a/content/en/userguide/reusable/Model Request.md +++ b/content/en/userguide/reusable/Model Request.md @@ -1,8 +1,8 @@ -**Responses for Request** +**Request** | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | -| title | string | Is the description of the Change Request | No | +| 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 | diff --git a/content/en/userguide/reusable/Model Success.md b/content/en/userguide/reusable/Model Success.md index aefcab73..9003061d 100644 --- a/content/en/userguide/reusable/Model Success.md +++ b/content/en/userguide/reusable/Model Success.md @@ -4,5 +4,5 @@ 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 | \ No newline at end of file +| success | boolean | Success or Failure. | Yes | +| error | string | Error message returned from API. | No | \ No newline at end of file