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 servers

A server is a resource, such as a physical server, a virtual machine, or any other logical unit, that can hold property values. Servers can be assigned to environments and can receive installed components for particular applications and environments.

GET /v1/servers

Returns all servers.

Filters

  • name — String for servers name
  • active — Boolean value to show active apps (default is to show only active apps)
  • inactive — Boolean value to show inactive apps

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/servers?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/servers?token=[api_token]

An example of filters:

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

GET /v1/servers/[id]

Returns a server by 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/servers/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/servers/[id]?token=[api_token]

POST /v1/servers

Creates a new server from posted data.

Required attributes

  • name — String name of the server

Optional attributes

  • dns — String value for the DNS name of the server
  • environment_ids — Array of integer IDs for environments to be associated with the group
  • ip_address — String value for the IP address of the server
  • os_platform — String value for the OS platform
  • property_ids — Array of integer IDs for properties to be linked to the group
  • server_group_ids — Array of integer IDs for server groups of which this server is a member

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 and 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 '<server><name>Sample Server</name><server_group_ids>1</server_group_ids><environment_ids>1</environment_ids><environment_ids>2</environment_ids></server>' http://[rails_host]/v1/servers?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"name":"Sample Server", "server_group_ids":[1], "environment_ids":[1,2]}' http://[rails_host]/v1/servers/?token=[api_token]

PUT /v1/servers/[id]

Updates an existing server with values from a posted document.

Editable attributes

  • name — String name of the server
  • dns — String value for the DNS name of the server
  • environment_ids — Array of integer IDs for environments to be associated with the group
  • ip_address — String value for the IP address of the server
  • os_platform — String value for the OS platform
  • property_ids — Array of integer IDs for properties to be linked to the group
  • server_group_ids — Array of integer IDs for server groups of which this server is a member

  • active — Boolean value to change the server state:

    • true for the active state
    • false for the inactive state

    Note

    Starting with BMC Release Process Management version 4.3.01.02, deactivating servers breaks their association with steps. Deactivating servers affects only steps in requests with the following states:

    Excerpt named Active step was not found in document xwiki:More-Products.Release-Lifecycle-Management.BMC-Release-Process-Management.brpm26.Using.Managing-configuration-of-applications-topology-and-infrastructure.Managing-environments.Associating-components-with-environments.WebHome.

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 and 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 '<server><name>Renamed Server</name></server>' http://[rails_host]/v1/servers/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "server": { "name" : "Renamed Server"}}'  http://[rails_host]/v1/servers/[id]?token=[api_token]

DELETE /v1/servers/[id]

Makes a server inactive. Sets the active parameter for the server 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

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 DELETE http://[rails_host]/v1/servers/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/servers/[id]?token=[api_token]

Sample output

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "455ca68fd934d7fb1ac2eac5d8956d2f"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 216ce9129078eab8260a6f1b8503b409
X-Runtime: 0.273000
Content-Type: application/json;charset=utf-8
Content-Length: 413
Date: Fri, 26 Oct 2012 06:47:03 GMT

[{
"active": true,
"created_at": "2012-10-26T02:30:27-04:00",
"dns": "www.example.com",
"id": 1,
"ip_address": "127.0.0.1",
"name": "Sample Server",
"os_platform": "Linux",
"updated_at": "2012-10-26T02:30:27-04:00",
"property_values": [],
"properties": [],
"server_aspects": [],
"environments": [{
"id": 1,
"name": "aws_cloud"
}, {
"id": 2,
"name": "production"
}],
"server_groups": [{
"id": 1,
"name": "Sample Server"
}],
"installed_components": []
}]

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "94e125c169a899bc9640a7fb3b7f8dd3"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: acc3c3bb310a8bafed931c420085298b
X-Runtime: 0.414000
Content-Type: application/xml;charset=utf-8
Content-Length: 933
Date: Fri, 26 Oct 2012 06:46:14 GMT

<?xml version="1.0" encoding="UTF-8"?>
<server>
 <active type="boolean">true</active>
 <created-at type="datetime">2012-10-26T02:30:27-04:00</created-at>
 <dns>www.example.com</dns>
 <id type="integer">1</id>
 <ip-address>127.0.0.1</ip-address>
 <name>Sample Server</name>
 <os-platform>Linux</os-platform>
 <updated-at type="datetime">2012-10-26T02:30:27-04:00</updated-at>
 <property-values type="array"/>
 <properties type="array"/>
 <server-aspects type="array"/>
 <environments type="array">
   <environment>
     <id type="integer">1</id>
     <name>aws_cloud</name>
   </environment>
   <environment>
     <id type="integer">2</id>
     <name>production</name>
   </environment>
 </environments>
 <server-groups type="array">
   <server-group>
     <id type="integer">1</id>
     <name>Sample Server</name>
   </server-group>
 </server-groups>
 <installed-components type="array"/>
</server>

Related topic

Managing-servers

 

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