REST servers

A server is a resource such as a physical server, 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 value 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", "agent_type": "NSH"  } }' 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
  • os_type—String value for the OS platform name
  • agent_type—String value for the agent type name for the remote dispatcher script

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

  • agent_type—String value for agent type name for the remote dispatcher script

  • agent_type_id—Integer value for agent type ID for the remote dispatcher script

    Note

    Either the agent_type or agent_type_id attribute can be used in the same request.

  • 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_type—String value for the OS platform names used in the automation script

  • os_type_id—Integer value for the OS platform ID

    Note

    Either the os_type or os_type_id attribute can be used in the same request.

  • 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><os_type>Linux</os_type></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], "os_type": "Linux" }' 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
  • agent_type—String value for the agent type name for the remote dispatcher script

  • agent_type_id—Integer value for the agent type ID for the remote dispatcher script

    Note

    Either the agent_type or agent_type_id attribute can be used in the same request.

  • 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_type—String value for the OS platform name

  • os_type_id—Integer value for the OS platform ID

    Note

    Either the os_type or os_type_id attribute can be used in the same request.

  • 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 active state
    • false for inactive state

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:

Status Code: 200 OK
Cache-Control: must-revalidate, private, max-age=0
Content-Length: 529
Content-Type: application/json;charset=utf-8
Date: Thu, 12 Nov 2015 12:19:34 GMT
Etag: "535943584d84c31783c44420e108511b"
Server: Apache-Coyote/1.1
X-Rack-Cache: miss
X-Request-Id: 128c7649f6d28dcb184f088775d11064
X-Runtime: 0.064000
X-UA-Compatible: IE=Edge,chrome=1
{
"active":true,
"created_at":"2015-05-25T08:34:27-04:00",
"dns":"www.example.com",
"id":10520,
"ip_address":"127.0.0.1",
"name":"Sample Server",
"updated_at":"2015-11-12T07:14:00-05:00",
"property_values":[],
"agent_type":{"id":10304,"value_text":"SSH"},
"os_type":{"id":10301,"value_text":"Linux"},
"properties":[{"id":11845,"name":"Sample Property"}],
"server_aspects":[],
"environments":[],
"server_groups":[{"id":10460,"name":"Sample Server Group 1"},
    {"id":10461,"name":"Sample Server Group 2"}],
"installed_components":[]
}

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

Status Code: 200 OK
Cache-Control: must-revalidate, private, max-age=0
Content-Type: application/xml;charset=utf-8
Date: Thu, 12 Nov 2015 12:08:47 GMT
Etag: "9610b3ec60600f770b893b2c7f055e85"
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
X-Rack-Cache: miss
X-Request-Id: d1968ba8131f1ff954e6b6d4288f341e
X-Runtime: 4.335000
X-UA-Compatible: IE=Edge,chrome=1

<server>
<active type="boolean">true</active>
<created-at type="datetime">2015-05-25T08:34:27-04:00</created-at>
<dns>www.exmaple.com</dns>
<id type="integer">10520</id>
<ip-address>127.0.0.1</ip-address>
<name>Sample Server</name>
<updated-at type="datetime">2015-05-25T08:34:27-04:00</updated-at>
<property-values type="array"/>
<agent-type type="ListItem">
<id type="integer">10304</id>
<value-text>SSH</value-text>
</agent-type>
<os-type type="ListItem">
<id type="integer">10301</id>
<value-text>Linux</value-text>
</os-type>
<properties type="array">
<property>
<id type="integer">11845</id>
<name>Sample Property</name>
</property>
</properties>
<server-aspects type="array"/>
<environments type="array"/>
<server-groups type="array">
<server-group>
<id type="integer">10460</id>
<name>Sample Server Group 1</name>
</server-group>
<server-group>
<id type="integer">10461</id>
<name>Sample Server Group 2</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*