Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Instances can be accessed and modified through this API using four services: GET, POST, PUT, and PATCH. These four services allow Instances can be accessed and modified through this API using four services: GET, POST, PUT, and PATCH. These four services allow for the retrieval, creation, complete update, and partial update of Instances.

...

Request

Parameter
Required
Type
Description
IdYesURLURL parameter for the Id which is used to find and return an instance

Include Page
REST V1 Instance Response
REST V1 Instance Response

Response Codes

HTTP Code
Description
200Instance was found and returned
400Bad request401Unauthorizedrequest
401Authentication failure
403Authorization failure (no access to resource)
404Instance not found
500Unexpected internal server error

Example

If we had an Instance in our database with an Id of 11004 with the following attributes

Code Block
themeEclipse
titleInstance - 11004
{
	"description": "GET example description",
	"environments": [11001],
	"workflows": [],
	"instanceId": 11004,
	"instanceName": "GET Example Name",
	"isActive": true, "pluginOperations": [],
	"instanceCode": "GETEXAMPLECODE",
	"groupCode": "GET example group",
	"subGroupCode": "GET example sub group",
	"isDeploymentTarget": false
}

When we run a GET request at the following URL

http://host:port/flexdeploy/rest/v1/topology/instance/11004

The GET request would return the following JSON Instance object

Code Block
themeEclipse
titleInstance GET Return JSON
{
	"description": "GET example description",
	"environments": [11001],
	"workflows": [],
	"instanceId": 11004,
	"instanceName": "GET Example Name",
	"isActive": true, "pluginOperations": [],
	"instanceCode": "GETEXAMPLECODE",
	"groupCode": "GET example group",
	"subGroupCode": "GET example sub group",
	"isDeploymentTarget": false
}

GET by Query Parameters

This GET service will return a list of Instances in the form of JSON objects based on the query parameters instanceCode, instanceName, groupCode, and subGroupCode. Instances are only returned if they match ALL of the specified query parameters. If no query parameters are given this request will return the entire list of Instances. The instanceName parameter returns instances that contain the specified parameter. The other parameters must be equal to the instance.

Info
titleAPI URL

http://host:port/flexdeploy/rest/v1/topology/instance?

Append the following character sequences to the above URL to specify Query parameters.
Use '&' between successive query parameters: 

instanceCode={instanceCode}

instanceName={instanceName}

groupCode={groupCode}

subGroupCode={subGroupCode}

Examples:
To Specify the code parameter only:

http://host:port/flexdeploy/rest/v1/topology/instance?instanceCode={instanceCode}

To Specify the code and group code parameters:

http://host:port/flexdeploy/rest/v1/topology/instance?instanceCode={instanceCode}&groupCode={groupCode}

To Specify the name, group code, and sub group code parameters:

http://host:port/flexdeploy/rest/v1/topology/instance?instanceName={instanceName}&groupCode={groupCode}&subGroupCode={subGroupCode}

...

Tip

The query parameters are not case sensitive. Searching by instanceName=NAME is the same as searching by instanceName=name.

Request

Parameter
Required
Type
Description
instanceCodeNoQuery - String

This is a URL query parameter for the instance code which is used to search the instances.

Equals ignore case search

instanceNameNoQuery - String

This is a URL query parameter for the instance name which is used to search the instances.

Contains ignore case search

groupCodeNoQuery - String

This is a URL query parameter for the group code which is used to search the instances.

Equals ignore case search

subGroupCodeNoQuery - String

This is a URL query parameter for the sub group code which is used to search the instances.

Equals ignore case search

Include Page
REST V1 Instance Response
REST V1 Instance Response

Response Codes

HTTP Code
Description
200Instances were found Search successful and results returned
400Bad request
401UnauthorizedAuthentication failure
403Authorization failure (no access to resource)
500Unexpected internal server error

...

Info
titleAPI URL

http://host:port/flexdeploy/rest/v1/topology/instance

Request

Attributes
Type
Required
Description
descriptionStringNoDescription of the Instance
environmentsList<Long>No

List of the Environment Ids that are associated with this instance.

All provided environments will be associated with instance.

workflowsList<Long>No

List of the workflow ids that are associated with this instance.

All provided workflows will be associated with instance.

instanceIdStringNoThe unique id of the instance. The id is made when making the instance, and it is returned in the JSON.
instanceNameStringYesName of the instance
isActiveBooleanNo

Whether or not this instance is active.

Defaults to true if nothing is passed.

plugins
pluginOperations

List<Plugin>

No

List of the plugin

ids

operations that are associated with this instance

All provided plugin operations will be associated with instance.

Plugin contains pluginId and operation attributes.

instanceCodeStringYesThe code of the Instance
groupCodeStringNoThe group code of the instance
subGroupCodeStringNoThe sub group code of the instance
isDeploymentTargetBooleanNo

Whether or not this instance is a deployment target.

Defaults to true if nothing is passed.

Include Page
REST V1 Instance Response
REST V1 Instance Response

...

HTTP Code
Description
201Instance was created successfully
400Bad request
401UnauthorizedAuthentication failure
404Instance not found403Authorization failure (no access to resource)
500Unexpected internal server error

...

Info
titleAPI URL

http://host:port/flexdeploy/rest/v1/topology/instance/{Id}

Request

Attributes
Type
Required
Description
IdURLYesURL parameter for the Id which is used to find and update an instance
descriptionStringNoDescription of the Instance
environmentsList<Long>No

List of

the Environment Ids that are associated with this instance

the Environment Ids that are associated with this instance. If currently associated environment(s) are not in input list those environments will be unassigned from this instance.

i.e. at the end of successful request, instance will have mapped environments matching to input request.

workflowsList<Long>No

List of the workflow ids that are associated with

this instance

this instance. If currently associated workflows(s) are not in input list those workflows will be unassigned from this instance.

i.e. at the end of successful request, instance will have mapped workflows matching to input request.

instanceIdStringNoThe instance Id in the request is ignored
instanceNameStringYesName of the instance
isActiveBooleanNo

Whether or not this instance is active.

Defaults to true if nothing is passed.

plugins
pluginOperationsList<Plugin>No

List of the plugins that are associated with this instance. If currently associated plugin operation(s) are not in input list those plugin operations will be unassigned from this instance.

i.e. at the end of successful request, instance will have mapped plugin operations matching to input request.

Plugin contains pluginId and operation attributes.

instanceCodeStringYesThe code of the Instance
groupCodeStringNoThe group code of the instance
subGroupCodeStringNoThe sub group code of the instance
isDeploymentTargetBooleanNo

Whether or not this instance is a deployment target.

Defaults to true if nothing is passed.

Include Page
REST V1 Instance Response
REST V1 Instance Response

Response Codes

HTTP Code
Description
200Instance was found and updated
400Bad request401Unauthorizedrequest
401Authentication failure
403Authorization failure (no access to resource)
404Instance not found
500Unexpected internal server error

Example

If we had an instance in our database with an Id of 11104 and had the following attributes

Code Block
titleCurrent Instance
collapsetrue
{
	"description": "Example description",
	"environments": [],
	"workflows": [],
	"instanceId": 11104,
	"instanceName": "Example Name",
	"isActive": false,
	"pluginOperations": [],
	"instanceCode": "EXAMPLECODE",
	"groupCode": "Group",
	"subGroupCode": "Sub Group",
	"isDeploymentTarget": false
}

When we run a PUT request at the following URL

http://host:port/flexdeploy/rest/v1/topology/instance/11104

And the PUT request receives the following JSON instance object,

Code Block
titleSample JSON Input
collapsetrue
{
	"description": "PUT description",
	"environments": [11001],
	"workflows": [11104],
	"instanceId": 1,
	"instanceName": "PUT Name",
	"isActive": true,
	"pluginOperations": [],
	"instanceCode": "PUTCODE",
	"groupCode": "PUT group",
	"subGroupCode": "PUT sub group",
	"isDeploymentTarget": true
}

The PUT request would then update the Instance with Id 11104 and return the  following JSON Instance object.

Code Block
titleSample JSON Output
collapsetrue
{
	"description": "PUT description",
	"environments": [11001],
	"workflows": [11104],
	"instanceId": 11104,
	"instanceName": "PUT Name",
	"isActive": true,
	"pluginOperations": [],
	"instanceCode": "PUTCODE",
	"groupCode": "PUT group",
	"subGroupCode": "PUT sub group",
	"isDeploymentTarget": true
}

PATCH

...

Tip

The only required attribute is the Instance Id in the URL.

Request

Attributes
Type
Required
Description
IdURLYesURL parameter for the Id which is used to find and update an instancedescriptionStringNoDescription of the Instanceenvironments
Description
IdURLYesURL parameter for the Id which is used to find and update an instance
descriptionStringNoDescription of the Instance
environmentsList<Long>No

List of the environment ids that will be added to the instance.

If input environment(s) is not already associated it will be associated to instance but existing environment assignment that are not in PATCH request will not be unassigned.

i.e. input list is considered as append to existing assignments.

workflowsList<Long>No

List of the

environment

workflow ids that will be added to the instance

workflowsList<Long>NoList of the workflow ids that will be added to the instance

.

If input workflow(s) is not already associated it will be associated to instance but existing workflow assignment that are not in PATCH request will not be unassigned.

i.e. input list is considered as append to existing assignments.

instanceIdStringNoThe instance Id in the request is ignored
instanceNameStringNoName of the instance
isActiveBooleanNoWhether or not this instance is active.
pluginsList<Plugin>No

List of the plugins that will be added to the instance.

If input plugin(s) is not already associated it will be associated to instance but existing plugin assignment that are not in PATCH request will not be unassigned.

i.e. input list is considered as append to existing assignments.

instanceCodeStringNoThe code of the Instance
groupCodeStringNoThe group code of the instance
subGroupCodeStringNoThe sub group code of the instance
isDeploymentTargetBooleanNoWhether or not this instance is a deployment target.

Include Page
REST V1 Instance Response
REST V1 Instance Response

...

HTTP Code
Description
200Instance was found and patched
400Bad request
401UnauthorizedAuthentication failure
403Authorization failure (no access to resource)
404Instance not found
500Unexpected internal server error

...