API: Servers
The Servers API is used to manage server definitions, which are used as ENC data by our Puppet infrastructure ("other end" of the ENC API), and to get status information about a server.
Please make sure to read the API Basics document before starting.
| This API previously had a different endpoint ('server-definitions' instead of 'servers'). The old endpoint still works, but doesn’t get new functionality and will eventually be removed. |
- Base URL
Fields: Server
| Name | Required | Description | Example Values |
|---|---|---|---|
fqdn |
yes |
Fully qualified domain name |
|
environment |
yes |
Puppet environment, set of Puppet module versions |
|
project |
yes |
A project name |
|
role |
yes |
The server’s role |
|
location |
yes |
The server’s location as defined in our hiera data (a set of datacenter specific parameters, for example, name server IPs or which backup server to use) |
|
region |
no |
CITY.CC, city code and country code of physical server location (a set of region specific parameters) |
|
zone |
no |
The server’s network zone |
|
stage |
no |
Production level of the project/server |
|
modDate |
generated |
Unix timestamp (ms) of last change. Type long (resp. double in JSON) |
1477493084029 |
modUser |
generated |
ID of user who did the last change |
|
Fields: Facts
There is no fixed list of which facts are available for a server. The following table lists a few common examples.
The value is currently always a String, even for structured facts.
| Name | Required | Description | Example Values |
|---|---|---|---|
processorcount |
no |
Number of CPU cores in the system |
|
lsbdistcodename |
no |
Code name of the Linux distribution |
"xenial" |
<String> |
no |
Name is usually self-explanatory |
<String> |
Methods
GET /
List all customer IDs you have access to.
$ curl https://control.vshn.net/api/servers/1/?accessToken=[...]
awesomeengineering
exampleinc
qq1soft
vshnGET /{customerId}/
List the fully qualified domain names of all servers of a customer. You can use the wildcard "_" for customerId, in which case you will see the servers of all customers you have access to.
$ curl https://control.vshn.net/api/servers/1/qq1soft/?accessToken=[...]
db0.qq1soft.com
db1.qq1soft.com
db2.qq1soft.com
jira.dev.qq1soft.com
web1.qq1soft.com
web2.qq1soft.comGET /{customerId}/{fqdn}
Get a server’s definition as JSON. You can use the wildcard "_" for customerId.
$ curl https://control.vshn.net/api/servers/1/qq1soft/jira.dev.qq1soft.com?accessToken=[...]{
"fqdn" : "jira.dev.qq1soft.com",
"customer" : "qq1soft",
"environment" : "QQ1Prod",
"project" : "dev",
"role" : "jira",
"location" : "cloudscale",
"stage" : "prod",
"modDate" : 1477493084029,
"modUser" : "qq-jdoe1"
}POST /{customerId}/
Create a new server definition. JSON payload.
$ curl -X POST -d '{"fqdn": "wiki.dev.qq1soft.com", "customer": "qq1soft", "environment": "QQ1Prod", "project": "dev", "role": "confluence", "location": "cloudscale", "stage": "prod"}' https://control.vshn.net/api/servers/1/qq1soft/?accessToken=[...]PUT /{customerId}/{fqdn}
Update an existing server definition. JSON payload. Which server to update is determined by the URL. You can use the wildcard "_" for customerId.
| The JSON must contain all fields that aren’t null, including those that remain the same (except fqdn, modDate modUser, which will be ignored). |
$ curl -X PUT -d '{"customer": "qq1soft", "environment": "QQ1Dev", "project": "dev", "role": "confluence", "location": "cloudscale", "stage": "prod"}' https://control.vshn.net/api/servers/1/qq1soft/wiki.dev.qq1soft.com?accessToken=[...]DELETE /{customerId}/{fqdn}
Delete an existing server definition. You can use the wildcard "_" for customerId.
$ curl -X DELETE https://control.vshn.net/api/servers/1/qq1soft/wiki.dev.qq1soft.com?accessToken=[...]