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
- include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
- alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.
Item | Associated items |
|---|---|
servers | property_values, agent_type, os_type, properties, server_aspects, environments, server_groups, installed_components |
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]
Filter examples:
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]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"properties,environments" }}' https://[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
Filters
- include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
- alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.
Item | Associated items |
|---|---|
servers | property_values, agent_type, os_type, properties, server_aspects, environments, server_groups, installed_components |
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]
Filter example:
curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"properties,environments" }}' https://[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
- New in 5.0.03.003description—String value for the description of the server
You can enter a maximum of 255 characters. - 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
- 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
- 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
Filters
- include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
- alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.
Item | Associated items |
|---|---|
servers | property_values, agent_type, os_type, properties, server_aspects, environments, server_groups, installed_components |
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><description>Production server></description><server_group_ids>1</server_group_ids><environment_ids>1</environment_ids><environment_ids>2</environment_ids><os_type>Linux</os_type></server><agent_type_id>200</agent_type_id>' 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", "agent_type_id": 201 }' http://[rails_host]/v1/servers/?token=[api_token]
Filter example:
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "server": {"name":"Rest Server 1", "server_group_ids":[1], "environment_ids":[1,2], "os_type": "Linux", "agent_type_id": 203 }, "filters": {"include_except" : "properties,environments"}}' https://[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
- New in 5.0.03.003description—String value for the description of the server
You can enter a maximum of 255 characters. - 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
- 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
- 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
Filters
- include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
- alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.
Item | Associated items |
|---|---|
servers | property_values, agent_type, os_type, properties, server_aspects, environments, server_groups, installed_components |
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><description>Test server</description></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]
Filter example:
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "server": { "name" : "Renamed Server 1"}, "filters": { "include_except":"properties,environments" }}' https://[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":[]
}
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>
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
Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*