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

     

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*