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.
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.
Version 2 of the Topology APIs rename Instance to Target Group, and Environment Instance to Target. The topology screens still refer to the old terminology, but will be updated in a future release as part of the new user experience. |
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.
http://host:port/flexdeploy/rest/v2/topology/environment/{Id} |
Parameter | Type | Required | Description |
|---|---|---|---|
Id | URL | Yes | This is a URL parameter for the Id which is used to find and return an environment |
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 |
If we had an environment in our database with an Id of 11101 and had the following attributes
{
"description": "This is Environment 1"
"targets": [],
"isActive": true,
"environmentCode": "ENV1",
"sortNumber": 1,
"environmentId": 11101,
"isBuildEnvironment": true,
"environmentName": "Env 1"
} |
http://host:port/flexdeploy/rest/v2/topology/environment/11101
The GET request would return the following JSON environment object
{
"description": "This is Environment 1",
"targets": [],
"isActive": true,
"environmentCode": "ENV1",
"sortNumber": 1,
"environmentId": 11101,
"isBuildEnvironment": true,
"environmentName": "Env 1"
} |
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.
http://host:port/flexdeploy/rest/v2/topology/environment? Append the following character sequences to the above URL to specify Query parameters.Use '&' between successive query parameters:environmentId={id} environmentCode={code} environmentName={name} isActive={boolean} isBuildEnvironment={boolean} sortNumber={number} Examples:To search by code only:http://host:port/flexdeploy/rest/v2/topology/environment?environmentCode={code} To search by name only:http://host:port/flexdeploy/rest/v2/topology/environment?environmentName={name} To search by code and name: |
The query parameters are not case sensitive. Searching by environmentName=NAME is the same as searching by environmentName=name. |
Parameter | Type | Required | Description |
|---|---|---|---|
| environmentId | Query - Long | No | This is a URL query parameter for id which is used to search the environments. Equals search |
environmentCode | Query - String | No | This is a URL query parameter for the code which is used to search the environments. 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 |
| isActive | Query - Boolean | No | This is a URL query parameter for is active which is used to search the environments. Equals search |
| isBuildEnvironment | Query - Boolean | No | This is a URL query parameter for is build environment which is used to search the environments. Equals search |
| sortNumber | Query - Integer | No | This is a URL query parameter for the sort number which is used to search the environments. Equals search |
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 |
If we had an environment in our database with an Id of 11101 and had the following attributes
{
"description": "This is Environment 1"
"targets": [],
"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/v2/topology/environment/?environmentCode=ENV1&environmentName=Env 1&isActive=true&sortNumber=1
The GET request would return the following JSON environment object
{
"description": "This is Environment 1",
"targets": [],
"isActive": true,
"environmentCode": "ENV1",
"sortNumber": 1,
"environmentId": 11101,
"isBuildEnvironment": true,
"environmentName": "Env 1"
} |
This POST service will create a new environment with the same attributes as the given JSON object.
Parameters | Type | Required | Description |
|---|---|---|---|
| description | String | No | This is the description that the created environment will have. |
| targets | List<Target> | No | This is the list of targetGroups that are assigned to the created environment. All provided targetGroups will be associated with this Environment. If a targetGroup is not found, it will be considered a bad request. |
| isActive | Boolean | Yes | This is the isActive boolean that is true if the created environment is active. |
| environmentCode | String | Yes | This is the Code that the created environment will have. |
| sortNumber | Integer | Yes | This is the sort number that the created environment will have. If no sort number sent, it will generate one. |
| environmentId | Long | Yes | This is the Id place holder. This Id will not be given to the created environment. |
| isBuildEnvironment | Boolean | Yes | This is the isBuildEnvironment boolean that is true if the created environment is a build environment. |
| environmentName | String | Yes | This is the name of the created environment. |
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 |
If the POST request receives the following JSON environment object,
{
"description": "This is Post 1",
"targets":
[
{
"targetGroupId": 15100
},
{
"targetGroupId": 15101
}
],
"isActive": true,
"environmentCode": "POST1",
"sortNumber": 1,
"isBuildEnvironment": true,
"environmentName": "Post 1"
} |
The following environment object will then be created as a new row in the database.
{
"description": "This is Environment 1",
"targets":
[
{
"targetGroupId": 15100,
"isActive": true,
"targetId": 10001,
"environmentId": 11101,
},
{
"targetGroupId": 15101,
"isActive": true,
"targetId": 10002,
"environmentId": 11101,
}
],
"isActive": true,
"environmentCode": "POST1",
"sortNumber": 1,
"environmentId": 11101,
"isBuildEnvironment": true,
"environmentName": "Post 1"
} |
If the POST request receives the following JSON environment object,
{
"description": "This is Post 1",
"isActive": true,
"environmentCode": "POST1",
"sortNumber": 1,
"isBuildEnvironment": true,
"environmentName": "Post 1"
} |
The following environment object will then be created as a new row in the database.
{
"description": "This is Post 1",
"targets": [],
"isActive": true,
"environmentCode": "POST1",
"sortNumber": 1,
"environmentId": 11101,
"isBuildEnvironment": true,
"environmentName": "Post 1"
} |
This PUT service will update all attributes of an environment with the given Id based on the attributes of a JSON object parameters.
http://host:port/flexdeploy/rest/v2/topology/environment/{Id} |
{
"description": "This is Put 1",
"targets": [],
"isActive": false,
"environmentCode": "PUT1",
"sortNumber": 6,
"environmentId": 00000,
"isBuildEnvironment": true,
"environmentName": "Put 1"
} |
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 | This is the description that the environment's description will be updated to. |
| targets | List<Target> | No | This is the list of targetGroups that will be assigned to the environment that is being updated. If currently associated targetGroup(s) are not in input list those targetGroups will be unassigned from this environment. If a targetGroup is not found, it will be considered a bad request. i.e. at the end of successful request, environment will have mapped targets 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 | This is the Code that the environment's Code will be updated to. |
| sortNumber | Integer | Yes | This is the sort number that the environment's sort number will be updated to. |
| environmentId | Long | Yes | This is the Id place holder. This Id will not be updated in the environment. |
| isBuildEnvironment | Boolean | Yes | This is the isBuildEnvironment boolean that the environment's isBuildEnvironment boolean will be updated to. |
| environmentName | String | Yes | This is the name that the environment's name will be updated to. |
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 |
If we had an environment in our database with an Id of 11101 and had the following attributes
{
"description": "This is Environment 1"
"targets":
[
{
"targetGroupId": 15100,
"isActive": true,
"targetId": 10001,
"environmentId": 11101,
}
],
"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/v2/topology/environment/11101
And the PUT request receives the following JSON environment object,
{
"description": "This is the updated Environment 1",
"targets":
[
{
"targetGroupId": 15101
}
],
"isActive": true,
"environmentCode": "PUT2",
"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
{
"description": "This is the updated Environment 1",
"targets":
[
{
"targetGroupId": 15101,
"isActive": true,
"targetId": 10002,
"environmentId": 11101,
}
],
"isActive": true,
"environmentCode": "PUT2",
"sortNumber": 2,
"environmentId": 11101,
"isBuildEnvironment": false,
"environmentName": "PUT 2"
} |
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.
By having a target in the JSON request the target will be added and no targetGroups will be unassigned. |
http://host:port/flexdeploy/rest/v2/topology/environment/{Id} |
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 | This is the description that the environment's description will be updated to. |
| targets | List<Target> | No | This is the list of targetGroups that will be assigned to the environment that is being updated. If input targetGroup(s) is not already assigned it will be assigned to environment but existing targetGroups assignment that are not in PATCH request will not be unassigned. If a targetGroup is not found, it will be considered a bad request. 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 | This is the code that the environment's code will be update to. |
| sortNumber | Integer | No | 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 | String | No | This is the name that the environment's name will be updated to. |
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 |
If we had an environment in our database with an Id of 11101 and had the following attributes
{
"description": "This is Environment 1",
"targets":
[
{
"targetGroupId": 15100,
"isActive": true,
"targetId": 10001,
"environmentId": 11101,
}
],
"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/v2/topology/environment/11101
And the PATCH request receives the following JSON environment object,
{
"description": "This is Patch with some null attributes",
"targets":
[
{
"targetGroupId": 15101
},
{
"targetGroupId": 15102
}
],
"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
{
"description": "This is Patch with some null attributes",
"targets":
[
{
"targetGroupId": 15100,
"isActive": true,
"targetId": 10001,
"environmentId": 11101,
},
{
"targetGroupId": 15101,
"isActive": true,
"targetId": 10002,
"environmentId": 11101,
},
{
"targetGroupId": 15102,
"isActive": true,
"targetId": 10003,
"environmentId": 11101,
}
],
"isActive": true,
"environmentCode": "ENV1",
"sortNumber": 7,
"environmentId": 11101,
"isBuildEnvironment": false,
"environmentName": "Patch with some null"
} |