Instance API

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.

Authentication - Use Basic Authentication for this API.

GET

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

GET by ID

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

API URL

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

Request

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

Response

Attributes
Type
Description
descriptionStringDescription of the Instance
environmentsList<Long>List of the Environment Ids that are associated with this instance
workflowsList<Long>List of the workflow ids that are associated with this instance
instanceIdStringThe unique id of the instance. The id is made when making the instance, and it is returned in the JSON.
instanceNameStringName of the instance
isActiveBooleanWhether or not this instance is active.
pluginOperationsList<PluginOperation>List of the plugin operations that are associated with this instance
instanceCodeStringThe code of the Instance
groupCodeStringThe group code of the instance
subGroupCodeStringThe sub group code of the instance
isDeploymentTargetBooleanWhether or not this instance is a deployment target.

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

AttributesTypeDescription
pluginIdLongThe plugin ID
operationStringThe name of the plugin operation

Response Codes

HTTP Code
Description
200Instance was found and returned
400Bad request
401Unauthorized
500Unexpected internal server error

Example

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

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

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

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}

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

Request

Parameter
Required
Type
Description
instanceCodeNoURLThis is a URL query parameter for the instance code which is used to search the instances.
instanceNameNoURLThis is a URL query parameter for the instance name which is used to search the instances.
groupCodeNoURLThis is a URL query parameter for the group code which is used to search the instances.
subGroupCodeNoURLThis is a URL query parameter for the sub group code which is used to search the instances.

Response

Attributes
Type
Description
descriptionStringDescription of the Instance
environmentsList<Long>List of the Environment Ids that are associated with this instance
workflowsList<Long>List of the workflow ids that are associated with this instance
instanceIdStringThe unique id of the instance. The id is made when making the instance, and it is returned in the JSON.
instanceNameStringName of the instance
isActiveBooleanWhether or not this instance is active.
pluginOperationsList<PluginOperation>List of the plugin operations that are associated with this instance
instanceCodeStringThe code of the Instance
groupCodeStringThe group code of the instance
subGroupCodeStringThe sub group code of the instance
isDeploymentTargetBooleanWhether or not this instance is a deployment target.

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

AttributesTypeDescription
pluginIdLongThe plugin ID
operationStringThe name of the plugin operation

Response Codes

HTTP Code
Description
200Instances were found and returned
400Bad request
401Unauthorized
500Unexpected internal server error

Example

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

Sample JSON Output
[
	{
		"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
	}
]

POST

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

API URL

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

Request

Attributes
Type
Required
Description
descriptionStringNoDescription of the Instance
environmentsList<Long>NoList of the Environment Ids that are associated with this instance
workflowsList<Long>NoList of the workflow ids that are associated with this 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.

pluginsList<Plugin>NoList of the plugin ids that are associated with this instance
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.

Response

Attributes
Type
Description
descriptionStringDescription of the Instance
environmentsList<Long>List of the Environment Ids that are associated with this instance
workflowsList<Long>List of the workflow ids that are associated with this instance
instanceIdStringThe unique id of the instance. The id is made when making the instance, and it is returned in the JSON.
instanceNameStringName of the instance
isActiveBooleanWhether or not this instance is active.
pluginOperationsList<PluginOperation>List of the plugin operations that are associated with this instance
instanceCodeStringThe code of the Instance
groupCodeStringThe group code of the instance
subGroupCodeStringThe sub group code of the instance
isDeploymentTargetBooleanWhether or not this instance is a deployment target.

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

AttributesTypeDescription
pluginIdLongThe plugin ID
operationStringThe name of the plugin operation

Response Codes

HTTP Code
Description
201Instance was created successfully
400Bad request
401Unauthorized
404Instance not found
500Unexpected internal server error

Example

If the POST receives the following JSON instance object,

Sample JSON Input
{
	"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 will be created in the database. Notice the updated Instance Id field.

Sample JSON Output
{
	"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
}

PUT

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

API 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>NoList of the Environment Ids that are associated with this instance
workflowsList<Long>NoList of the workflow ids that are associated with this instance
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.

pluginsList<Plugin>NoList of the plugins that are associated with this instance
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.

Response

Attributes
Type
Description
descriptionStringDescription of the Instance
environmentsList<Long>List of the Environment Ids that are associated with this instance
workflowsList<Long>List of the workflow ids that are associated with this instance
instanceIdStringThe unique id of the instance. The id is made when making the instance, and it is returned in the JSON.
instanceNameStringName of the instance
isActiveBooleanWhether or not this instance is active.
pluginOperationsList<PluginOperation>List of the plugin operations that are associated with this instance
instanceCodeStringThe code of the Instance
groupCodeStringThe group code of the instance
subGroupCodeStringThe sub group code of the instance
isDeploymentTargetBooleanWhether or not this instance is a deployment target.

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

AttributesTypeDescription
pluginIdLongThe plugin ID
operationStringThe name of the plugin operation

Response Codes

HTTP Code
Description
200Instance was found and updated
400Bad request
401Unauthorized
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

Current Instance
{
	"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,

Sample JSON Input
{
	"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.

Sample JSON Output
{
	"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

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

API URL

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

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 instance
descriptionStringNoDescription of the Instance
environmentsList<Long>NoList of the environment ids that will be added to the instance
workflowsList<Long>NoList of the workflow ids that will be added to the instance
instanceIdStringNoThe instance Id in the request is ignored
instanceNameStringNoName of the instance
isActiveBooleanNoWhether or not this instance is active.
pluginsList<Plugin>NoList of the plugins that will be added to the instance
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.

Response

Attributes
Type
Description
descriptionStringDescription of the Instance
environmentsList<Long>List of the Environment Ids that are associated with this instance
workflowsList<Long>List of the workflow ids that are associated with this instance
instanceIdStringThe unique id of the instance. The id is made when making the instance, and it is returned in the JSON.
instanceNameStringName of the instance
isActiveBooleanWhether or not this instance is active.
pluginOperationsList<PluginOperation>List of the plugin operations that are associated with this instance
instanceCodeStringThe code of the Instance
groupCodeStringThe group code of the instance
subGroupCodeStringThe sub group code of the instance
isDeploymentTargetBooleanWhether or not this instance is a deployment target.

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

AttributesTypeDescription
pluginIdLongThe plugin ID
operationStringThe name of the plugin operation

Response Codes

HTTP Code
Description
200Instance was found and patched
400Bad request
401Unauthorized
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

Current Instance
{
	"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,

Sample JSON Input
{
	"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 instance with Id 11104 and return the following JSON instance object.

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