Versions Compared

Key

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

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

Table of Contents
maxLevel2

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

...

Back to Top

Environments 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
maxLevel2

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.

...

Info
titleAPI URL

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

...

Request

Parameter
Type
Required
Description

Id

URLYesThis is a URL parameter for the Id which is used to find and return an environmentenvironment

Include Page
REST V1 Environment Response
REST V1 Environment Response

Response Codes

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

Example

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

Code Block
themeEclipse
titleEnvironment - 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
themeEclipse
titleEnvironment 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 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
titleAPI 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: 

environmentCode={code}

environmentName={name}

Examples:
To search by code only:

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

To search by name only:

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

To search by code and name:

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

...

Tip

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

...

Request

Parameter
Type
Required
Description

environmentCode

URL
Query - StringNo

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

Equals ignore case search

environmentName
URL
Query - StringNo

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
Environments were found
Search successful and results returned
400Bad request
401
Unauthorized
Authentication failure
403Authorization failure (no access to resource)
500Unexpected internal server error

Example

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

Code Block
themeEclipse
titleEnvironment - 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/?code=ENV1&name=Env 1

The GET request would return the  following JSON environment object

Code Block
themeEclipse
titleEnvironment 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

POST

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

Info
titleAPI URL

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

Parameters

Request

Parameters
Type
Required
Description
descriptionStringNoThis is the description that the created environment will have.
instancesList<Long>No

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.

isActiveBooleanYesThis is the isActive boolean that is true if the created environment is active.
environmentCodeStringYesThis is the Code that the created environment will have.
sortNumberIntegerYesThis is the sort number that the created environment will have.
environmentIdLongYesThis is the Id place holder. This Id will not be given to the created environment.
isBuildEnvironmentBooleanYesThis is the isBuildEnvironment boolean that is true if the created environment is a build environment.
environmentNameStringYesThis is the name of the created environment.

Include Page
REST V1 Environment Response
REST V1 Environment Response

Response Codes

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

Example

If the POST request receives the following JSON environment object,

Code Block
themeEclipse
titlePOST 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
themeEclipse
titleEnvironment 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
titleAPI URL

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


Code Block
themeEclipse
titleSample PUT JSON Request
{
   "description": "This is Put 1",
   "instances": [15100],
   "isActive": false,
   "environmentCode": "PUT1",
   "sortNumber": 6,
   "environmentId": 00000,
   "isBuildEnvironment": true,
   "environmentName": "Put 1"
}
Parameters

Request

Parameters
Type
Required
Description
IdURLYesThis is a URL parameter for the Id which is used to find and return an environment with.
descriptionStringNoThis is the description that the environment's description will be updated to.
instancesList<Long>No

This is the list of Instance Ids 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

environment that is being updated

end of successful request, environment will have mapped instances matching to input request.

isActiveBooleanYesThis is the isActive boolean that the environment's isActive boolean will be updated to.
environmentCodeStringYesThis is the Code that the environment's Code will be updated to.
sortNumberIntegerYesThis is the sort number that the environment's sort number will be updated to.
environmentIdLongYesThis is the Id place holder. This Id will not be updated in the environment.
isBuildEnvironmentBooleanYesThis is the isBuildEnvironment boolean that the environment's isBuildEnvironment boolean will be updated to.
environmentNameStringYesThis 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
200Environment was found and updated
400Bad request
401UnauthorizedAuthentication failure
403Authorization failure (no access to resource)
404Environment not found
500Unexpected internal server error

Example

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

...

Code Block
themeEclipse
titleEnvironment PUT Return JSON
{
   "description": "This is the updated Environment 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
titleInstance Adding Functionality

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

...

Info
titleAPI URL

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

Parameters

Request

Parameters
Type
Required
Description
IdURLYesThis is a URL parameter for the Id which is used to find and return an environment with.
descriptionStringNoThis is the description that the environment's description will be updated to.
instancesList<Long>No

This is the list of instance Ids

that

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

If input instance(s) is not already assigned it will be assigned to

the

environment but existing instances assignment that

is being updated

are not in PATCH request will not be unassigned.

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

isActiveBooleanNoThis is the isActive boolean that the environment's isActive boolean will be updated to.
environmentCodeStringNoThis is the code that the environment's code will be update to.
sortNumberIntegerNoThis is the sort number that the environment's sort number will be updated to.
environmentIdLongNoThis is the Id place holder. It will not change the environment's Id that is being updated. 
isBuildEnvironmentBooleanNoThis is the isActive boolean that the environment's isActive boolean will be updated to.
environmentNameStringNoThis 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
200Environment was found and patched
400Bad request
401UnauthorizedAuthentication failure
403Authorization failure (no access to resource)
404Environment not found
500Unexpected internal server error

Example

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

Code Block
themeEclipse
titleEnvironment 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
themeEclipse
titleEnvironment 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
themeEclipse
titleEnvironment 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