Information
Unsupported content This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

REST environments


An environment encompasses a set of servers and resources grouped together for a particular purpose in the deployment process — for example, a development environment, a quality assurance environment, or a production environment.

GET /v1/environments

Returns all the environments.

Filters

  • name — String value for the environment name
  • active — Boolean value to show active environments (default is to show only active environments)
  • environment_type_id — Filter environments by environment type ID
  • inactive — Boolean value to show inactive environments

Common attributes

  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not Found — Occurs when no records are found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/environments?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/environments?token=[api_token]

An example of filters:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "name":"Sample Environment" } }' http://[rails_host]/v1/environments?token=[api_token]

GET /v1/environments/[id]

Returns an environment by the ID.

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure to include an accept header or add .xml or .json  to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when record to show is not found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/environments/[id]?token=[api_token] 
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/environments/[id]?token=[api_token]

POST /v1/environments

Creates a new environment from the posted data.

Required attributes

  • name — String name of the environment (must be unique)

Optional attributes

  • active — Boolean value for active (default is true)
  • default_server_group_id — Integer ID of default server group ID (optional)
  • default — Boolean value for default (optional, default false)
  • server_group_ids — Array of integer IDs for related server groups
  • server_ids — Array of integer IDs for related servers
  • environment_type_id — ID of environment type

Common attributes

  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 422 Unprocessable entity — Occurs when validation fails, objects and errors are returned

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d '<environment><name>REST Environment</name></environment>' http://[rails_host]/v1/environments?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"environment" : { "name":"Rest Environment" } }' http://[rails_host]/v1/environments/?token=[api_token]

PUT /v1/environments/[id]

Updates an existing environment with values from a posted document.

Editable attributes

  • active — Boolean value for active (default is true)
  • default_server_group_id — Integer ID of default server group ID (optional)
  • default — Boolean value for default (optional, default false)
  • name — String name of the environment (must be unique)
  • server_group_ids — Array of integer IDs for related server groups
  • server_ids — Array of integer IDs for related servers
  • environment_type_id – ID of environment type

Common attributes

  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when record to update is not found
  • ERROR 422 Unprocessable entity — Occurs when validation fails, objects and errors are returned

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X PUT -d '<environment><name>Renamed Environment</name></environment>' http://[rails_host]/v1/environments/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "environment": { "name" : "Renamed Environment" } }'  http://[rails_host]/v1/environments/[id]?token=[api_token]

DELETE /v1/environments/[id]

Makes an environment inactive. Sets the active parameter for the environment to false..

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when no records are found

Sample output

The following JSON is a sample output from GET /v1/environments:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "3ce446175438137b6a914c322e17dac8"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: bec5332ee6968fab5e2cc8f9d7e79fb6
X-Runtime: 1.154000
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked
Date: Tue, 23 Oct 2012 14:45:59 GMT

[{
"active": true,
"created_at": "2011-04-29T00:12:28-04:00",
"default": false,
"default_server_group_id": null,
"id": 2,
"name": "production",
"updated_at": "2011-04-29T00:12:28-04:00",
"apps": [{
"id": 2,
"name": "App 2"
}, {
"id": 1,
"name": "SR_|_SmartRelease"
}],
"assigned_apps": [{
"id": 3
}, {
"id": 1
}],
"assigned_environments": [{
"id": 5
}, {
"id": 2
}],
"requests": [],
"servers": [{
"id": 1,
"name": "Test Server 1"
}, {
"id": 2,
"name": "Test Server 2"
}, {
"id": 3,
"name": "Test Server 3"
}],
"server_groups": [{
"id": 1,
"name": "Test Server Group 1"
}],
"installed_components": [{
"application_component_id": 4,
"application_environment_id": 2,
"default_server_group_id": null,
"id": 8,
"location": null,
"reference_id": null,
"version": null,
"component": {
"id": 4,
"name": "SS_MySQL"
},
"app": {
"id": 1,
"name": "SR_|_SmartRelease"
}
}, {
"application_component_id": 5,
"application_environment_id": 2,
"default_server_group_id": null,
"id": 10,
"location": null,
"reference_id": null,
"version": null,
"component": {
"id": 5,
"name": "SS_RailsApp"
},
"app": {
"id": 1,
"name": "SR_|_SmartRelease"
}
}, {
"application_component_id": 1,
"application_environment_id": 2,
"default_server_group_id": null,
"id": 2,
"location": null,
"reference_id": null,
"version": null,
"component": {
"id": 1,
"name": "AppContainer"
},
"app": {
"id": 1,
"name": "SR_|_SmartRelease"
}
}, {
"application_component_id": 3,
"application_environment_id": 2,
"default_server_group_id": null,
"id": 6,
"location": null,
"reference_id": null,
"version": null,
"component": {
"id": 3,
"name": "SS_Passenger"
},
"app": {
"id": 1,
"name": "SR_|_SmartRelease"
}
}, {
"application_component_id": 10,
"application_environment_id": 5,
"default_server_group_id": null,
"id": 20,
"location": null,
"reference_id": null,
"version": null,
"component": {
"id": 5,
"name": "SS_RailsApp"
},
"app": {
"id": 2,
"name": "App 2"
}
}, {
"application_component_id": 2,
"application_environment_id": 2,
"default_server_group_id": null,
"id": 4,
"location": null,
"reference_id": null,
"version": "",
"component": {
"id": 2,
"name": "SS_Apache"
},
"app": {
"id": 1,
"name": "SR_|_SmartRelease"
}
}]
"environment_type": {
        
"description":"A default environment type.",
        
"id":4,
        
"name":"Production"
    
},
    
"route_gates": [{
        "description":null,
        "id":5,
        "route": {
            "id":3,
            "name":"Another Production Route",           
"route_type":"open"
        }
    }, {
        "description":null,
        "id":4,
        "route": {
            "id":1,
            "name":"[default]",
            "
route_type":"open"
        }
    }, {
        "
description":null,
        "
id":3,
        "
route": {
            "
id":2,
            "
name":"Production Route",
            "
route_type":"open"
        
}
    
}]
}]

The following XML is a sample output from GET /v1/environments/1:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "1ddc103bdbdda86ce3c3112058221a08"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 093ddc6f62581546d3051bedb0251426
X-Runtime: 0.427000
Content-Type: application/xml;charset=utf-8
Transfer-Encoding: chunked
Date: Tue, 23 Oct 2012 14:50:01 GMT

<?xml version="1.0" encoding="UTF-8"?>
<environment>
  
<active type="boolean">true</active>
  
<created-at type="datetime">2011-04-29T00:12:28-04:00</created-at>
  
<default type="boolean">false</default>
  
<default-server-group-id type="integer" nil="true"></default-server-group-id>
  
<id type="integer">1</id>
  
<name>aws_cloud</name>
  
<updated-at type="datetime">2011-04-29T00:12:28-04:00</updated-at>
  
<apps type="array">
    
<app>
      
<id type="integer">2</id>
      
<name>App 2</name>
    
</app>
    
<app>
      
<id type="integer">1</id>
      
<name>SR_|_SmartRelease</name>
    
</app>
  
</apps>
  
<assigned-apps type="array">
    
<assigned-app>
      
<id type="integer">3</id>
    
</assigned-app>
    
<assigned-app>
      
<id type="integer">1</id>
    
</assigned-app>
  
</assigned-apps>
  
<assigned-environments type="array">
    
<assigned-environment>
      
<id type="integer">4</id>
    
</assigned-environment>
    
<assigned-environment>
      
<id type="integer">1</id>
    
</assigned-environment>
  
</assigned-environments>
  
<requests type="array">
    
<request>
      
<aasm-state>complete</aasm-state>
      
<id type="integer">3</id>
      
<name>Request Example</name>
    
</request>
  
</requests>
  
<servers type="array">
    
<server>
      
<id type="integer">1</id>
      
<name>Test Server 1</name>
    
</server>
    
<server>
      
<id type="integer">2</id>
      
<name>Test Server 2</name>
    
</server>
    
<server>
      
<id type="integer">3</id>
      
<name>Test Server 3</name>
    
</server>
  
</servers>
  
<server-groups type="array">
    
<server-group>
      
<id type="integer">1</id>
      
<name>Test Server Group 1</name>
    
</server-group>
  
</server-groups>
  
<installed-components type="array">
    
<installed-component>
      
<application-component-id type="integer">4</application-component-id>
      
<application-environment-id type="integer">1</application-environment-id>
      
<default-server-group-id type="integer" nil="true"></default-server-group-id>
      
<id type="integer">7</id>
      
<location nil="true"></location>
      
<reference-id type="integer" nil="true"></reference-id>
      
<version nil="true"></version>
      
<component>
        
<id type="integer">4</id>
        
<name>SS_MySQL</name>
      
</component>
      
<app>
        
<id type="integer">1</id>
        
<name>SR_|_SmartRelease</name>
      
</app>
    
</installed-component>
    
<installed-component>
      
<application-component-id type="integer">5</application-component-id>
      
<application-environment-id type="integer">1</application-environment-id>
      
<default-server-group-id type="integer" nil="true"></default-server-group-id>
      
<id type="integer">9</id>
      
<location nil="true"></location>
      
<reference-id type="integer" nil="true"></reference-id>
      
<version nil="true"></version>
      
<component>
        
<id type="integer">5</id>
        
<name>SS_RailsApp</name>
      
</component>
      
<app>
        
<id type="integer">1</id>
        
<name>SR_|_SmartRelease</name>
      
</app>
    
</installed-component>
    
<installed-component>
      
<application-component-id type="integer">1</application-component-id>
      
<application-environment-id type="integer">1</application-environment-id>
      
<default-server-group-id type="integer" nil="true"></default-server-group-id>
      
<id type="integer">1</id>
      
<location nil="true"></location>
      
<reference-id type="integer" nil="true"></reference-id>
      
<version nil="true"></version>
      
<component>
        
<id type="integer">1</id>
        
<name>AppContainer</name>
      
</component>
      
<app>
        
<id type="integer">1</id>
        
<name>SR_|_SmartRelease</name>
      
</app>
    
</installed-component>
    
<installed-component>
      
<application-component-id type="integer">3</application-component-id>
      
<application-environment-id type="integer">1</application-environment-id>
      
<default-server-group-id type="integer" nil="true"></default-server-group-id>
      
<id type="integer">5</id>
      
<location nil="true"></location>
      
<reference-id type="integer" nil="true"></reference-id>
      
<version nil="true"></version>
      
<component>
        
<id type="integer">3</id>
        
<name>SS_Passenger</name>
      
</component>
      
<app>
        
<id type="integer">1</id>
        
<name>SR_|_SmartRelease</name>
      
</app>
    
</installed-component>
    
<installed-component>
      
<application-component-id type="integer">6</application-component-id>
      
<application-environment-id type="integer">4</application-environment-id>
      
<default-server-group-id type="integer" nil="true"></default-server-group-id>
      
<id type="integer">11</id>
      
<location nil="true"></location>
      
<reference-id type="integer" nil="true"></reference-id>
      
<version nil="true"></version>
      
<component>
        
<id type="integer">1</id>
        
<name>AppContainer</name>
      
</component>
      
<app>
        
<id type="integer">2</id>
        
<name>App 2</name>
      
</app>
    
</installed-component>
    
<installed-component>
      
<application-component-id type="integer">7</application-component-id>
      
<application-environment-id type="integer">4</application-environment-id>
      
<default-server-group-id type="integer" nil="true"></default-server-group-id>
      
<id type="integer">13</id>
      
<location nil="true"></location>
      
<reference-id type="integer" nil="true"></reference-id>
      
<version nil="true"></version>
      
<component>
        
<id type="integer">2</id>
        
<name>SS_Apache</name>
      
</component>
      
<app>
        
<id type="integer">2</id>
        
<name>App 2</name>
      
</app>
    
</installed-component>
    
<installed-component>
      
<application-component-id type="integer">8</application-component-id>
      
<application-environment-id type="integer">4</application-environment-id>
      
<default-server-group-id type="integer" nil="true"></default-server-group-id>
      
<id type="integer">15</id>
      
<location nil="true"></location>
      
<reference-id type="integer" nil="true"></reference-id>
      
<version nil="true"></version>
      
<component>
        
<id type="integer">4</id>
        
<name>SS_MySQL</name>
      
</component>
      
<app>
        
<id type="integer">2</id>
        
<name>App 2</name>
      
</app>
    
</installed-component>
    
<installed-component>
      
<application-component-id type="integer">9</application-component-id>
      
<application-environment-id type="integer">4</application-environment-id>
      
<default-server-group-id type="integer" nil="true"></default-server-group-id>
      
<id type="integer">17</id>
      
<location nil="true"></location>
      
<reference-id type="integer" nil="true"></reference-id>
      
<version nil="true"></version>
      
<component>
        
<id type="integer">3</id>
        
<name>SS_Passenger</name>
      
</component>
      
<app>
        
<id type="integer">2</id>
        
<name>App 2</name>
      
</app>
    
</installed-component>
    
<installed-component>
      
<application-component-id type="integer">10</application-component-id>
      
<application-environment-id type="integer">4</application-environment-id>
      
<default-server-group-id type="integer" nil="true"></default-server-group-id>
      
<id type="integer">19</id>
      
<location nil="true"></location>
      
<reference-id type="integer" nil="true"></reference-id>
      
<version nil="true"></version>
      
<component>
        
<id type="integer">5</id>
        
<name>SS_RailsApp</name>
      
</component>
      
<app>
        
<id type="integer">2</id>
        
<name>App 2</name>
      
</app>
    
</installed-component>
    
<installed-component>
      
<application-component-id type="integer">2</application-component-id>
      
<application-environment-id type="integer">1</application-environment-id>
      
<default-server-group-id type="integer">1</default-server-group-id>
      
<id type="integer">3</id>
      
<location nil="true"></location>
      
<reference-id type="integer" nil="true"></reference-id>
      
<version></version>
      
<component>
        
<id type="integer">2</id>
        
<name>SS_Apache</name>
      
</component>
      
<app>
        
<id type="integer">1</id>
        
<name>SR_|_SmartRelease</name>
      
</app>
    
</installed-component>
  
</installed-components>
  
<environment-type>
    
<description>A default environment type.</description>
    
<id type="integer">4</id>
    
<name>Production</name>
  
</environment-type>
  
<route-gates type="array">
    
<route-gate>
      
<description nil="true"></description>
      
<id type="integer">5</id>
      
<route>
      
<id type="integer">3</id>
        
<name>Another Production Route</name>   
<route-type>open</route-type>
      
</route>
    
</route-gate>
    
<route-gate>
      
<description nil="true"></description>
      
<id type="integer">4</id>
      
<route>
        
<id type="integer">1</id>
        
<name>[default]</name>    
<route-type>open</route-type>
      
</route>
    
</route-gate>
    
<route-gate>
      
<description nil="true"></description>
      
<id type="integer">3</id>
      
<route>
        
<id type="integer">2</id>
        
<name>Production Route</name>     
<route-type>open</route-type>
      
</route>
    
</route-gate>
  
</route-gates>
</environment>

Related topic

REST-API-commands

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

BMC Release Process Management 4.3