...

Info

title	Base URL for Environment REST API

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

Overview:

...

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

Each function returns a JSON environment object. The environment object has these attributes:

...

Back to Top

AnchorGETGETEnvironments 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 environments.

Include Page

	REST V1 Authentication
	REST V1 Authentication

Table of Contents

maxLevel	2

GET

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

...

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

Info

title	API URL

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

...

Request

TypeURL

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

ExpandtitleGET by ID Example

and return an environment

Include Page

	REST V1 Environment Response
	REST V1 Environment Response

Response Codes

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

Example

If we had an environment in our database with an Id of 11101 and had the following attributes

Code Block

theme	Eclipse
title	Environment - 11101

{
   "description": "This is Environment 1" 
   "instances": [15100],
   "isActive": true,
   "environmentCode": "ENV1",
   "sortNumber": 1,
   "environmentId": 11101,
   "isBuildEnvironment": true,
   "environmentName": "Env 1"
}

When we run a GET request at the following URL

http://host:port/flexdeploy/rest/v1/topology/environment/11101

The GET request would return the following JSON environment object

Code Block

theme	Eclipse
title	Environment GET Return JSON

{
   "description": "This is Environment 1",
   "instances": [15100],
   "isActive": true,
   "environmentCode": "ENV1",
   "sortNumber": 1,
   "environmentId": 11101,
   "isBuildEnvironment": true,
   "environmentName": "Env 1"
}

Back to Top

GET (Using Query Parameters)

This GET service will return a list of environments in the form of JSON objects based on the query parameters code and name. Environments are only returned if they match all of the specified query parametersall of the specified query parameters. The name query parameter searches if any environment contains the value given in there name while all other query parameters check if any environment has attributes that are equal to the parameter value. If no query parameters are given this request will return the entire list of environments.

Info

title	API URLs

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

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

Use '&' between successive query parameters:

codeenvironmentCode={code}

nameenvironmentName={name}

Examples:

To search by code only:

http://host:port/flexdeploy/rest/v1/topology/environment?codeenvironmentCode={code}

To search by name only:

http://host:port/flexdeploy/rest/v1/topology/environment?nameenvironmentName={name}

To search by code and name:

http://host:port/flexdeploy/rest/v1/topology/environment?codeenvironmentCode={code}&nameenvironmentName={name}

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

...

Request

http://host:port/flexdeploy/rest/topology/environment/?code=ENV1&name=Env 1

The GET request would return the following JSON environment object

Parameter	Type	Required

Type

	Description

Code

NoURLThis is a URL query parameter for the code which is used to search the environments.NameNoURL

environmentCode

Query - String

No

This is a URL query parameter for the

name

code which is used to search the environments.

Expand

title	GET (Using Query Parameters) Example

Example

If we had an environment in our database with an Id of 11101 and had the following attributes

Code Block

theme	Eclipse
title	Environment - 11101

{
   "description": "This is Environment 1" 
   "instances": [15100],
   "isActive": true,
   "environmentCode": "ENV1",
   "sortNumber": 1,
   "environmentId": 11101,
   "isBuildEnvironment": true,
   "environmentName": "Env 1"
}

When we run a GET request at the following URL

Equals ignore case search

environmentName

Query - String

No

This is a URL query parameter for the name which is used to search the environments. The environment name parameter checks if any environment name contains the value given.

Contains ignore case search

Include Page

	REST V1 Environment Response
	REST V1 Environment Response

Response Codes

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

Example

...

If we had an environment in our database with an Id of 11101 and had the following attributes

GET Return JSON

Code Block

theme	Eclipse
title	Environment

- 11101

{
   "description":

 "This is Environment 1"

,

 
   "instances": [15100],
   "isActive": true,
   "environmentCode": "ENV1",
   "sortNumber": 1,
   "environmentId": 11101,
   "isBuildEnvironment": true,
   "environmentName": "Env

1" }

Back to Top

...

POST

This POST service will create a new environment with the same attributes as the given JSON object.

...

 1"
}

When we run a GET request at the following URL

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

...

/environment/?code=ENV1&name=Env 1

The GET request would return the following JSON environment object

Code Block

title
theme	Eclipse

...

Environment GET Return JSON

...

{
   "description": "This is

...

Environment 1",
   "instances": [15100

...

],
   "isActive": true,
   "environmentCode": "

...

ENV1",
   "sortNumber": 1,
   "environmentId":

...

 11101,
   "isBuildEnvironment": true,

...

Parameters

Required

Type

Description

descriptionNoString

   "environmentName": "Env 1"
}

POST

This POST service will create a new environment with the same attributes as the given JSON object.

Info

title	API URL

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

Request

titlePost Example

Parameters	Type	Required	Description
description	String	No	This is the description that the created environment will have.
instances	List<Long>	No

List<Long>

This is the list of Instance Ids that are assigned to the created environment.

All provided instances will be associated with Environment. If instances not found, it will be considered bad request.

isActive

Boolean

Yes

Boolean

	This is the isActive boolean that is true if the created environment is active.
environmentCode	String	Yes

String

	This is the Code that the created environment will have.
sortNumber	Integer	Yes

Integer

	This is the sort number that the created environment will have.
environmentId	Long	Yes

Long

	This is the Id place holder. This Id will not be given to the created environment.
isBuildEnvironment	Boolean	Yes

Boolean

This is the isBuildEnvironment boolean that is true if

the created environment is a build environment.environmentNameYesStringThis is the name of the created environment.

Expand

the created environment is a build environment.
environmentName	String	Yes	This is the name of the created environment.

Include Page

	REST V1 Environment Response
	REST V1 Environment Response

Response Codes

HTTP Code	Description
201	Environment was created successfully
400	Bad request
401	Authentication failure
403	Authorization failure (no access to resource)
500	Unexpected internal server error

Example

...

If the POST request receives the following JSON environment object,

Code Block

theme	Eclipse
title	POST JSON

{
   "description": "This is Post 1",
   "instances": [15100,15101],
   "isActive": true,
   "environmentCode": "POST1",
   "sortNumber": 1,
   "environmentId":00000,
   "isBuildEnvironment": true,
   "environmentName": "Post 1"
}

The following environment object will then be created as a new row in the database.

Code Block

theme	Eclipse
title	Environment Post Return JSON

{
   "description": "This is Environment 1",
   "instances": [15100],
   "isActive": true,
   "environmentCode": "ENV1",
   "sortNumber": 1,
   "environmentId": 11101,
   "isBuildEnvironment": true,
   "environmentName": "Env 1"
}

Back to Top

...

PUT

This PUT service will update all attributes of an environment with the given Id based on the attributes of a JSON object parameters.

Info

title	API URL

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

Code Block

theme	Eclipse
title	Sample PUT JSON Request

{
   "description": "This is Put 1",
   "instances": [15100],
   "isActive": false,
   "environmentCode": "PUT1",
   "sortNumber": 6,
   "environmentId": 00000,
   "isBuildEnvironment": true,
   "environmentName": "Put 1"
}

Request

Parameters

Parameters

Type	Required

Type

	Description
Id	URL	Yes

URL

	This is a URL parameter for the Id which is used to find and return an environment with.
description	String	No

String

	This is the description that the environment's description will be updated to.
instances	List<Long>	No

List<Long>

This is the list of Instance Ids

that will be assigned to the environment that is being updated.isActiveYesBoolean

that will be assigned to the environment that is being updated. If currently associated instance(s) are not in input list those instances will be unassigned from this environment.

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

isActive

Boolean

Yes

This is the isActive boolean that the environment's isActive boolean will be updated to.

environmentCode

String

Yes

String

	This is the Code that the environment's Code will be updated to.
sortNumber	Integer	Yes

Integer

	This is the sort number that the environment's sort number will be updated to.
environmentId	Long	Yes

Long

	This is the Id place holder. This Id will not be updated in the environment.
isBuildEnvironment	Boolean	Yes

Boolean

	This is the isBuildEnvironment boolean that the environment's isBuildEnvironment boolean will be updated to.
environmentName	String	Yes

String

This is the name that the environment's name will be updated to.

...

title	PUT Example

Example

If we had an environment in our database with an Id of 11101 and had the following attributes

Code Block

theme	Eclipse
title	Environment PUT JSON

{
   "description": "This is Environment 1" 
   "instances": [15100],
   "isActive": true,
   "environmentCode": "ENV1",
   "sortNumber": 1,
   "environmentId": 11101,
   "isBuildEnvironment": true,
   "environmentName": "Env 1"
}

When we run a PUT request at the following URL

http://host:port/flexdeploy/rest/topology/environment/11101

...

Include Page

	REST V1 Environment Response
	REST V1 Environment Response

Response Codes

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

Example

If we had an environment in our database with an Id of 11101 and had the following attributes

Receive

Code Block

theme	Eclipse
title	Environment PUT

JSON

{
   "description":

 "This is

the

updated

Environment 1"

,

 
   "instances": [

15101

15100],
   "isActive": true,
   "environmentCode": "

PUT2

ENV1",
   "sortNumber":

2

 1,
   "environmentId": 11101,
   "isBuildEnvironment":

false

 true,
   "environmentName": "Env 1"

PUT 2" }The PUT request would then update the environment with Id 11101 and return the

When we run a PUT request at the following URL

http://host:port/flexdeploy/rest/v1/topology/environment/11101

And the PUT request receives the following JSON environment object,

Return

Code Block

theme	Eclipse
title	Environment PUT

Receive JSON

{
   "description": "This is the updated Environment 1

", "instances": [15101], "isActive": true,

environmentCode": "PUT2", "sortNumber": 2

,
   "

environmentId

instances":

11101

[15101],
   "

isBuildEnvironment

isActive":

false

 true,
   "

environmentName

environmentCode": "PUT2"

PUT

2" }

Back to Top

...

PATCH

This PATCH service will update an existing environment with the information passed through a JSON object. If an attribute of the JSON is null it will not be updated in the environment.

Info

title	API URL

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

   "sortNumber": 2,
   "environmentId": 11101,
   "isBuildEnvironment": false,
   "environmentName": "PUT 2"
}

The PUT request would then update the environment with Id 11101 and return the following JSON environment object

Code Block

title
theme	Eclipse

...

Environment PUT Return JSON

...

   "description":

...

 "This is

...

the

...

updated

...

Environment

...

Parameters

...

Parameters

...

Required

...

Type

...

Description

...

1",
   "instances": [15101],
   "isActive": true,
   "environmentCode": "PUT2",
   "sortNumber": 2,
   "environmentId": 11101,
   "isBuildEnvironment": false,
   "environmentName": "PUT 2"
}

PATCH

This PATCH service will update an existing environment with the information passed through a JSON object. If an attribute of the JSON is null it will not be updated in the environment.

Info

title	Instance Adding Functionality

By having an instance in the JSON request the instance will be added and no instances will be unassigned.

Info

title	API URL

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

Request

List<Long>BooleanLongBoolean

Parameters	Type	Required	Description
Id	URL	Yes	This is a URL parameter for the Id which is used to find and return an environment with.
description	String	No	String	This is the description that the environment's description will be updated to.
instances	List<Long>	No		This is the list of instance Ids that will be assigned to the environment that is being updated. If input instance(s) is not already assigned it will be assigned to environment but existing instances assignment that are not in PATCH request will not be unassigned. i.e. input list is considered as append to existing assignments.
isActive	Boolean	No		This is the isActive boolean that the environment's isActive boolean will be updated to.
environmentCode	String	No	String	This is the code that the environment's code will be update to.
sortNumber	Integer	No	Integer	This is the sort number that the environment's sort number will be updated to.
environmentId	Long	No		This is the Id place holder. It will not change the environment's Id that is being updated.
isBuildEnvironment	Boolean	No		This is the isActive boolean that the environment's isActive boolean will be updated to.
environmentName	No	String	This is the name that the environment's name will be updated to.

ExpandtitlePATCH Example

will be updated to.
environmentName	String	No	This is the name that the environment's name will be updated to.

Include Page

	REST V1 Environment Response
	REST V1 Environment Response

Response Codes

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

Example

If we had an environment in our database with an Id of 11101 and had the following attributes

Code Block

theme	Eclipse
title	Environment PATCH JSON

{
   "description": "This is Environment 1",
   "instances": [15101],
   "isActive": true,
   "environmentCode": "ENV1",
   "sortNumber": 1,
   "environmentId": 11101,
   "isBuildEnvironment": false,
   "environmentName": "Env 1"
}

When we run a PATCH request at the following URL

http://host:port/flexdeploy/rest/v1/topology/environment/11101

And the PATCH request receives the following JSON environment object,

Code Block

theme	Eclipse
title	Environment PATCH Receive JSON

{
   "description": "This is Patch with some null attributes",
   "instances": [15101,15102,15103],
   "isActive": null,
   "environmentCode": null,
   "sortNumber": 7,
   "environmentId": null,
   "isBuildEnvironment": false,
   "environmentName": "Patch with some null"
}

The PATCH request would then update the environment with Id 11101 and return the following JSON environment object

Code Block

theme	Eclipse
title	Environment PATCH Return JSON

{
   "description": "This is Patch with some null attributes",
   "instances": [15101,15102,15103],
   "isActive": true,
   "environmentCode": "ENV1",
   "sortNumber": 7,
   "environmentId": 11101,
   "isBuildEnvironment": false,
   "environmentName": "Patch with some null"
}

Back to Top

Versions Compared

Old Version 2

New Version Current

Key

Jump To:

Overview:

GET

Request

Response Codes

Example

GET (Using Query Parameters)

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

Use '&' between successive query parameters:

Examples:

To search by code only:

To search by name only:

To search by code and name:

Request

Example

Response Codes

Example

POST

Parameters

POST

Request

Response Codes

Example

PUT

Request

Example

Response Codes

Example

PATCH

Parameters

PATCH

Request

Response Codes

Example

Page Comparison

Versions Compared

Old Version 2

New Version Current

Key

Jump To:

Overview:

GET

Request

Response Codes

Example

GET (Using Query Parameters)

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

Use '&' between successive query parameters:

Examples:

To search by code only:

To search by name only:

To search by code and name:

Request

Example

Response Codes

Example

POST

Parameters

POST

Request

Response Codes

Example

PUT

Request

Example

Response Codes

Example

PATCH

Parameters

PATCH

Request

Response Codes

Example