# 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.

 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.

## Fields: Server

Name Required Description Example Values

fqdn

yes

Fully qualified domain name

`"web1.qq1soft.com"`

environment

yes

Puppet environment, set of Puppet module versions

`"QQ1Prod"`

project

yes

A project name

`"website", "developertools"`

role

yes

The server’s role

`"app", "db", "reverseproxy"`

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)

`"cloudscale", "ec2"`

region

no

CITY.CC, city code and country code of physical server location (a set of region specific parameters)

`"zrh.ch"`

zone

no

The server’s network zone

`"internal"`

stage

no

Production level of the project/server

`"prod", "stage", "dev"`

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

`"qq-jdoe1", "john.doe"`

## 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

`"1", "2"`

lsbdistcodename

no

Code name of the Linux distribution

"xenial"

<String>

no

Name is usually self-explanatory

<String>

## Methods

### `GET /`

Example
``````$curl https://control.vshn.net/api/servers/1/?accessToken=[...] awesomeengineering exampleinc qq1soft vshn`````` #### Status codes 200 OK 403 Authentication error ### `GET /{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. Example ``````$ 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.com``````

#### Status codes

200

OK

403

Authentication error

404

### `GET /{customerId}/{fqdn}`

Get a server’s definition as JSON. You can use the wildcard "_" for `customerId`.

Example

#### Status codes

201

Created

400

Input validation error

403

Authentication error

404

### 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).
Example

#### Status codes

200

OK

403

Authentication error

404

Customer ID or `fqdn` not found

### `GET /{customerId}/{fqdn}/facts`

Get all facts of a server. You can use the wildcard "_" for `customerId`.

Example
``\$ curl https://control.vshn.net/api/servers/1/qq1soft/jira.dev.qq1soft.com/facts?accessToken=[...]``
Response
``````{
"lsbdistcodename" : "xenial",
"processorcount" : "2",
[...]
}``````

#### Status codes

200

OK

403

Authentication error

404

Customer ID or `fqdn` not found