Anchor

	Top
	Top

...

Overview:

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

...

You can find more information about the REST API functions on the Topology REST API page.

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

Required*NoNoNoYesNo

Attributes	Type		Description
Description	String		Description of the Instance
Environments	List<Long>		List of the Environment Ids that are associated with this instance
Workflows	List<Long>		List of the workflow ids that are associated with this instance
Instance Id	String	No	The unique id of the instance. The id is made when making the instance, and it is returned in the JSON.
Instance Name	String		Name of the instance
isActive	Boolean	No**	Whether or Whether or not this instance is active.
Plugins	List<Plugin>		List of the plugin ids that are associated with this instance
Instance Code	String	Yes	The code of the Instance
Group Code	StringNo	The group code of the instance
Sub Group Code	String	No	The sub group code of the instance
isDeploymentTarget	BooleanNo**	Whether or not this instance is a deployment target.

*unless otherwise stated

...

Back to Top

...

Anchor

	GET
	GET

GET

...

Parameters

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

expand

Response Codes

title	GET by ID Example

Example

If we had an Instance in our database with an

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

Example

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

Code Block

theme	Eclipse
title	Instance - 11004

{
	"description": "GET example description",
	"environments": [11001],
	"workflows": [],
	"instanceId": 11004,
	"instanceName": "GET Example Name",
	"isActive": true, "plugins": [],
	"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/topology/instance/11004

The GET request would return the following JSON Instance object

Code Block

theme	Eclipse
title	Instance GET Return JSON

{
	"description": "GET example description",
	"environments": [11001],
	"workflows": [],
	"instanceId": 11004,
	"instanceName": "GET Example Name",
	"isActive": true, "plugins": [],
	"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 in the form of JSON objects based on the query parameters code, name, group code, and sub group code. 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.

Info

title	API URL

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

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

Use '&' between successive query parameters:

code={code}

name={name}

groupcode={groupcode}

subgroupcode={subgroupcode}

Examples:

To Specify the code parameter only:

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

To Specify the code and group code parameters:

http://host:port/flexdeploy/rest/topology/instance?code={code}&groupcode={groupcode}

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

http://host:port/flexdeploy/rest/topology/instance?name={name}&groupcode={groupcode}&subgroupcode={subgroupcode}

...

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

Parameters

Parameter	Required	Type	Description
Code	No	URL	This is a URL query parameter for the code which is used to search the instances.
Name	No	URL	This is a URL query parameter for the name which is used to search the instances.
Group Code	No	URL	This is a URL query parameter for the group code which is used to search the instances.
Sub Group Code	No	URL	This is a URL query parameter for the sub group code which is used to search the instances.

Response Codes

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

Example

...

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

...

Back to Top

Anchor

	POST
	POST

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.

If the POST receives the following JSON instance object,

Info

title	API URL

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

Expand

title	POST Example

Code Block

title	Sample JSON Input
collapse	true

{
	"description": "POST example description",
	"environments": [11001],
	"workflows": [],
	"instanceId": 1,
	"instanceName": "POST Example Name",
	"isActive": true,
	"plugins": [],
	"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.

Code Block

title	Sample JSON Output
collapse	true

{ "description": "POST example description", "

Parameters

Attributes	Type	Required	Description
Description	String	No	Description of the Instance
Environments	List<Long>	No	List of the Environment Ids that are associated with this instance
Workflows	List<Long>	No	List of the workflow ids that are associated with this instance
Instance Id	String	No	The unique id of the instance. The id is made when making the instance, and it is returned in the JSON.
Instance Name	String	Yes	Name of the instance
isActive	Boolean	No*	Whether or not this instance is active.
Plugins	List<Plugin>	No	List of the plugin ids that are associated with this instance
Instance Code	String	Yes	The code of the Instance
Group Code	String	No	The group code of the instance
Sub Group Code	String	No	The sub group code of the instance
isDeploymentTarget	Boolean	No*	Whether or not this instance is a deployment target.

*defaults to true if nothing is passed

Response Codes

HTTP Code	Description
201	Instance was created successfully
400	Bad request
401	Unauthorized
404	Instance not found
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":

11004

1,
	"instanceName": "POST Example Name",
	"isActive": true,
	"plugins": [],
	"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 with the given Id based on the attributes of the supplied JSON object.

Info

title	API URL

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

...

title	PUT Example

Example

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

...

title	Current Instance
collapse	true

...

the following Instance 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,
	"plugins": [],
	"instanceCode": "

...

POSTEXAMPLECODE",
	"groupCode": "

...

POST example group",
	"subGroupCode": "

...

POST example sub group",
	"isDeploymentTarget": false
}

...

When we run a PUT request at the following URL

Back to Top

Anchor

	PUT
	PUT

PUT

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

Info

title	API URL

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

...

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,
	"plugins": [],
	"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

title	Sample JSON Output
collapse	true

{
	"description": "PUT description",
	"environments": [11001],
	"workflows": [11104],
	"instanceId": 11104,
	"instanceName": "PUT Name",
	"isActive": true,
	"plugins": [],
	"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 of the specified Id with the non-null parameters of the JSON. The parameters that are null will not be changed in the Instance.

Info

title	API URL

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

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

...

{Id}

Parameters

Attributes	Type	Required	Description
Id	URL	Yes	URL parameter for the Id which is used to find and update an instance
Description	String	No	Description of the Instance
Environments	List<Long>	No	List of the Environment Ids that are associated with this instance
Workflows	List<Long>	No	List of the workflow ids that are associated with this instance
Instance Id	String	No	The instance Id in the request is ignored
Instance Name	String	Yes	Name of the instance
isActive	Boolean	No*	Whether or not this instance is active.
Plugins	List<Plugin>	No	List of the plugin ids that are associated with this instance
Instance Code	String	Yes	The code of the Instance
Group Code	String	No	The group code of the instance
Sub Group Code	String	No	The sub group code of the instance
isDeploymentTarget	Boolean	No*	Whether or not this instance is a deployment target.

*defaults to true if nothing is passed

Response Codes

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

Example

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

Code Block

title	Current Instance
collapse	true

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

When we run a PUT request at the following URL

http://host:port/flexdeploy/rest/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,
	"plugins": [],
	"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

title	Sample JSON Output
collapse	true

{
	"description": "PUT description",
	"environments": [11001],
	"workflows": [11104],
	"instanceId": 11104,
	"instanceName": "PUT Name",
	"isActive": true,
	"plugins": [],
	"instanceCode": "PUTCODE",
	"groupCode": "PUT group",
	"subGroupCode": "PUT sub group",
	"isDeploymentTarget": true
}

Back to Top

Anchor

	PATCH
	PATCH

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.

Info

title	API URL

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

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

Parameters

Attributes	Type	Required	Description
Id	URL	Yes	URL parameter for the Id which is used to find and update an instance
Description	String	No	Description of the Instance
Environments	List<Long>	No	List of the Environment Ids that are associated with this instance
Workflows	List<Long>	No	List of the workflow ids that are associated with this instance
Instance Id	String	No	The instance Id in the request is ignored
Instance Name	String	No	Name of the instance
isActive	Boolean	No	Whether or not this instance is active.
Plugins	List<Plugin>	No	List of the plugin ids that are associated with this instance
Instance Code	String	No	The code of the Instance
Group Code	String	No	The group code of the instance
Sub Group Code	String	No	The sub group code of the instance
isDeploymentTarget	Boolean	No	Whether or not this instance is a deployment target.

Response Codes

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

Example

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

Code Block

title	Current Instance
collapse	true

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

When we run a PATCH request at the following URL

http://host:port/flexdeploy/rest/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,
	"plugins": 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.

Code Block

title	Sample JSON Output
collapse	true

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

Back to Top

...

Versions Compared

Old Version 4

New Version 5

Key

Overview:

GET

Parameters

Response Codes

Example

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:

Parameters

Response Codes

POST

Parameters

Response Codes

Example

PUT

Example

PUT

PATCH

Parameters

Response Codes

Example

PATCH

Parameters

Response Codes

Example

Page Comparison

Versions Compared

Old Version 4

New Version 5

Key

Overview:

GET

Parameters

Response Codes

Example

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:

Parameters

Response Codes

POST

Parameters

Response Codes

Example

PUT

Example

PUT

PATCH

Parameters

Response Codes

Example

PATCH

Parameters

Response Codes

Example