AnchorTopTop

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

Info

title	Base URL for Instance REST API

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

Table of Contents

maxLevel	2

Each function returns a JSON Instance object. An Instance object has these attributes:

...

Attributes

...

Type

...

Description

...

A plugin operation, relative to an instance, is defined by the following two fields.

...

Back to Top

...

Target Groups 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 Target Groups.

Include Page

	REST V1 Authentication
	REST V1 Authentication

Table of Contents

maxLevel	2

GET

There are two implementations of GET. One will find an Instance a Target Group with the given Id and return the JSON representation of the InstanceTarget Group. The other will find a list of Instances Target Groups matching the parameters supplied to it.

GET by ID

This GET service will find an Instance a Target Group with the given Id and return the JSON representation of the object.

Info

title	API URL

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

Parameters

Request

Parameter	Required	Type	Description
Id	Yes	URL	URL parameter for the Id which is used to find and return an instancefind and return a target group

Include Page

	REST V1 Target Group Response
	REST V1 Target Group Response

Response Codes

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

Example

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

Code Block

theme	Eclipse
title	Instance Target Group - 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

theme	Eclipse
title	Instance Target Group 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
}

Back to Top

GET by Query Parameters

This GET service will return a list of Instances Target Groups in the form of JSON objects based on the query parameters instanceCode, instanceName, groupCode, and subGroupCode. Instances Target Groups 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 Target Groups that contain the specified parameter. The other parameters must be equal to the instanceTarget Group.

Info

title	API 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
instanceCode	No

URL

Query - String

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

instances

Target Groups.

Equals ignore case search

instanceName

No

URL

Query - String

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

instances

Target Groups.

Contains ignore case search

groupCode

No

URL

Query - String

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

instances

Target Groups.

Equals ignore case search

subGroupCode

No

URL

Query - String

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

instances.

Target Groups.

Equals ignore case search

Include Page

	REST V1 Target Group Response
	REST V1 Target Group Response

Response Codes

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

Example

Output when the Group Code was made "Group" through http://host:port/flexdeploy/rest/v1/topology/instance?groupCode=Group

Code Block

title	Sample JSON Output
collapse	true

[
	{
		"description": "GET example description",
		"environments": [10001],
		"workflows": [10001],
		"instanceId": 10000,
		"instanceName": "GET Example Name",
		"isActive": true,
		"pluginOperations": [{"propertySetName":"pluginName","ownerId":12345}],
		"instanceCode": "GETEXAMPLECODE",
		"groupCode": "Group",
		"subGroupCode": "GET example sub group",
		"isDeploymentTarget": false
	},
	{ 
		"description": "GET example 2 description", 
		"environments": [10001, 10002, 10003], 
		"workflows": [10001, 10002, 10003], 
		"instanceId": 10012, 
		"instanceName": "GET Example 2 Name", 
		"isActive": true, 
		"pluginOperations": [], 
		"instanceCode": "GETEXAMPLECODE2", 
		"groupCode": "group", 
		"subGroupCode": "GET example 2 sub group", 
		"isDeploymentTarget": true
	}
]

Back to Top

...

POST

The POST service will create a new instance Target Group with the same attributes as the given JSON object. It returns the JSON representation of the Instance Target Group that was just created with an updated ID attribute.

Info

title	API URL

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

...

Request

Attributes	Type	Required	Description
description	String	No	Description of

the Instance

the Target Group
environments	List<Long>	No	List of the Environment Ids that are associated with this

instance

Target Group.

All provided environments will be associated with Target Group.

workflows

List<Long>

No

List of the workflow

ids that are associated with this instance

ids that are associated with this Target Group.

All provided workflows will be associated with Target Group.

instanceId

String

No

The unique id of the

instance

Target Group. The id is made when

making

creating the

instance

Target Group, and it is returned in the JSON.
instanceName	String	Yes	Name of

the instance

the Target Group
isActive	Boolean	No

*

Whether or not this

instance

Target Group is active.

plugins

Defaults to true if nothing is passed.
pluginOperations	List<Plugin>	No	List of the plugin

ids

operations that are

associated with this instance

associated with this Target Group

All provided plugin operations will be associated with Target Group.

Plugin contains pluginId and operation attributes.

instanceCode

String

Yes

The code of

the Instance

the Target Group.
groupCode	String	No	The group code of

the instance

the Target Group.
subGroupCode	String	No	The sub group code of the

instance

Target Group.
isDeploymentTarget	Boolean	No

*

Whether or not this

instance

Target Group is a deployment target.

...

Defaults to true if nothing is passed.

Include Page

	REST V1 Target Group Response
	REST V1 Target Group Response

Response Codes

HTTP Code	Description
201	Instance Target Group was created successfully
400	Bad request
401Unauthorized	Authentication failure
404	Instance not found403	Authorization failure (no access to resource)
500	Unexpected internal server error

Example

If the POST receives the following JSON instance object,

Code Block

title	Sample JSON Input
collapse	true

{
	"description": "POST example description",
	"environments": [11001],
	"workflows": [],
	"instanceId": 1,
	"instanceName": "POST Example Name",
	"isActive": true,
	"pluginOperations": [],
	"instanceCode": "POSTEXAMPLECODE",
	"groupCode": "POST example group",
	"subGroupCode": "POST example sub group",
	"isDeploymentTarget": false
}

the following Instance Target Group will be created in the database. Notice the updated Instance Id field.

Code Block

title	Sample JSON Output
collapse	true

{
	"description": "POST example description",
	"environments": [11001],
	"workflows": [],
	"instanceId": 11004,
	"instanceName": "POST Example Name",
	"isActive": true,
	"pluginOperations": [],
	"instanceCode": "POSTEXAMPLECODE",
	"groupCode": "POST example group",
	"subGroupCode": "POST example sub group",
	"isDeploymentTarget": false
}

Back to Top

...

PUT

This PUT service will update all attributes of an Instance a Target Group with the given Id based on the attributes of the supplied JSON object.

Info

title	API URL

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

...

Parameters

Request

Attributes	Type	Required	Description
Id	URL	Yes	URL parameter for the Id which is used to find and update

an instancedescriptionStringNoDescription of the Instanceenvironments

a Target Group.
description	String	No	Description of the Target Group.
environments	List<Long>	No	List of the Environment Ids that are associated with this Target Group. If currently associated environment(s) are not in input list those environments will be unassigned from this Target Group. i.e. at the end of successful request, Target Group will have mapped environments matching to input request.
workflows	List<Long>	No	List of the

Environment Ids

workflow ids that are associated with this

instanceworkflowsList<Long>NoList of the workflow ids that are associated with this instance

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

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

instanceId

String

No

The instance Id in the request is ignored

instanceName

String

Yes

Name of

the instanceisActiveBooleanNo*Whether or not this instance is active.pluginsList<Plugin>NoList of the plugins that are associated with this instance

the Target Group
isActive	Boolean	No	Whether or not this Target Group is active. Defaults to true if nothing is passed.
pluginOperations	List<Plugin>	No	List of the plugins that are associated with this Target Group. If currently associated plugin operation(s) are not in input list those plugin operations will be unassigned from this Target Group. i.e. at the end of successful request, Target Group will have mapped plugin operations matching to input request. Plugin contains pluginId and operation attributes.
instanceCode	String	Yes	The code of

the Instance

the Target Group.
groupCode	String	No	The group code of

the instance

the Target Group.
subGroupCode	String	No	The sub group code of

the instance

the Target Group.
isDeploymentTarget	Boolean	No

*

Whether or not this

instance

Target Group is a deployment target.

*defaults

Defaults to true if

nothing is passed

nothing is passed.

Include Page

	REST V1 Target Group Response
	REST V1 Target Group Response

Response Codes

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

Example

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

Code Block

title	Current InstanceTarget Group
collapse	true

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

title	Sample JSON Input
collapse	true

{
	"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 Target Group with Id 11104 and return the following JSON Instance object.

Code Block

title	Sample JSON Output
collapse	true

{
	"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
}

Back to Top

...

PATCH

This PATCH service will update the information of the Instance Target Group of the specified Id with the non-null parameters of the JSON. The parameters that are null will not be changed in the Instance.

...

Tip
The only required attribute is the Instance Target Group Id in the URL.

...

Request

Attributes	Type	Required	Description
Id	URL	Yes	URL parameter for the Id which is used to find and update

an instancedescriptionStringNoDescription of the Instanceenvironments

a Target Group.
description	String	No	Description of the Target Group.
environments	List<Long>	No	List of the environment ids that will be added to the Target Group. If input environment(s) is not already associated it will be associated to Target Group 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.
workflows	List<Long>	No	List of the

environment

workflow ids that will be added to the

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

Target Group.

If input workflow(s) is not already associated it will be associated to Target Group 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.

instanceId

String

No

The instance Id in the request is ignored

instanceName

String

No

Name of

the instance

the Target Group
isActive	Boolean	No	Whether or not this

instance

Target Group is active.
plugins	List<Plugin>	No	List of the plugins that will be added to the

instance

Target Group.

If input plugin(s) is not already associated it will be associated to the Target Group 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.

instanceCode

String

No

The code of

the Instance

the Target Group.
groupCode	String	No	The group code of

the instance

the Target Group.
subGroupCode	String	No	The sub group code of

the instance

the Target Group.
isDeploymentTarget	Boolean	No	Whether or not this

instance

Target Group is a deployment target.

Include Page

	REST V1 Target Group Response
	REST V1 Target Group Response

Response Codes

HTTP Code	Description
200

Instance

Target Group was found and patched
400	Bad request
401

Unauthorized

	Authentication failure
403	Authorization failure (no access to resource)
404	Instance not found
500	Unexpected internal server error

Example

If we had

...

a Target Group in our database with an Id of 11104 and had the following attributes

Code Block

title	Current

...

Target Group
collapse	true

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

When we run a PATCH request at the following URL

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

And the PATCH request receives the following JSON instance object,

Code Block

title	Sample JSON Input
collapse	true

{
	"description": "PATCH example description",
	"environments": null,
	"workflows": null,
	"instanceId": null,
	"instanceName": null,
	"isActive": null,
	"pluginOperations": null,
	"instanceCode": "PATCHEXAMPLECODE",
	"groupCode": null,
	"subGroupCode": null,
	"isDeploymentTarget": null
}

The PATCH request would then update the

...

Target Group with Id 11104 and return the following JSON instance object.

Code Block

title	Sample JSON Output
collapse	true

{
	"description": "PATCH example description",
	"environments": [11001],
	"workflows": [],
	"instanceId": 11104,
	"instanceName": "Example Name",
	"isActive": false,
	"pluginOperations": [],
	"instanceCode": "PATCHEXAMPLECODE",
	"groupCode": "Group",
	"subGroupCode": "Sub Group",
	"isDeploymentTarget": false
}

...

Versions Compared

Old Version 21

New Version Current

Key

GET

GET by ID

Request

Response Codes

Example

GET by Query Parameters

Append the following character sequences to the above URL to specify Query parameters.

Use '&' between successive query parameters:

Examples:

To Specify the code parameter only:

To Specify the code and group code parameters:

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

Request

Response Codes

Example

POST

Request

Response Codes

Example

PUT

PUT

Request

Response Codes

Example

PATCH

Request

Response Codes

Example

Page Comparison

Versions Compared

Old Version 21

New Version Current

Key

GET

GET by ID

Request

Response Codes

Example

GET by Query Parameters

Append the following character sequences to the above URL to specify Query parameters.

Use '&' between successive query parameters:

Examples:

To Specify the code parameter only:

To Specify the code and group code parameters:

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

Request

Response Codes

Example

POST

Request

Response Codes

Example

PUT

PUT

Request

Response Codes

Example

PATCH

Request

Response Codes

Example