fluke/devops-service/doc/server.md

# Servers API

## Get servers list [GET /v3/servers]
> Get servers list

### Request
  * Policy: read_servers
  * Method: GET
  * Headers:
    *  Accept: application/json
  * Params:

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
[
  {
    "id" : "server id",
    "name" : "server name",
    "cm_name" : "server configuration manager name",
    "remote_user" : "ssh remote user",
    "project": "project id",
    "environment": "environment id",
    "category": "category id",
    "private_ip": "private IP address",
    "public_ip": "public IP address",
    "created_by": "server owner",
    "reserved_by": "server reserved by",
    "stack": "server stack name",
    "ssh_key": "ssh key id",
    "run_list": "server run list"
  }
]
```

## Get cm servers list [GET /v3/servers/cm_tool/:cm_tool]
> Get servers list for configuration tool :cm_tool

### Request
  * Policy: read_servers
  * Method: GET
  * Headers:
    *  Accept: application/json
  * Params:

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
[
  {
  }
]
```

## Get provider servers list [GET /v3/servers/provider/:provider/:account]
> Get servers list for provider :provider and account :account

### Request
  * Policy: read_servers
  * Method: GET
  * Headers:
    *  Accept: application/json
  * Params:

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
[
  {
  }
]
```

## Get server id by name [GET /v3/server/id/:name]
> Get server id by name :name

### Request
  * Policy: read_servers
  * Method: GET
  * Headers:
    *  Accept: application/json
  * Params:

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server id"
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```

## Get server [GET /v3/server/:id]
> Get server by id

### Request
  * Policy: read_servers
  * Method: GET
  * Headers:
    *  Accept: application/json
  * Params:

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{}
```

## Create server [POST /v3/server]
> Create new server

### Request
  * Policy: create_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json
    *  X-Stream: true -> return output in text stream
  * Body:
```json
{
  "project": "project name", -> mandatory parameter
  "environment": "env",      -> mandatory parameter
  "category": "env",         -> mandatory parameter
  "name": "server_name",     -> if null, name will be generated
  "without_bootstrap": null, -> do not install chef on instance if true
  "force": null              -> do not delete server on error
}

```

### Response
**Status: 201**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server_id"
  "message" : "Created"
}
```

## Delete server [DELETE /v3/server/:id]
> Delete server with id ':id'

### Request
  * Policy: delete_servers
  * Method: DELETE
  * Headers:
    *  Accept: application/json

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{}
```

## Pause server [POST /v3/server/:id/pause]
> pause cloud server with identifier ':id'

### Request
  * Policy: pause_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server_id"
  "message" : "Paused"
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```

## Unpause server [POST /v3/server/:id/unpause]
> unpause cloud server with identifier ':id'

### Request
  * Policy: pause_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server_id"
  "message" : "Unpaused"
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```

## Reserve server [POST /v3/server/:id/reserve]
> Reserve server with identifier ':id'

### Request
  * Policy: reserve_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server_id"
  "message" : "Reserved"
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```

## Unreserve server [POST /v3/server/:id/unreserve]
> Unreserve server with identifier ':id'

### Request
  * Policy: reserve_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server_id"
  "message" : "Unreserved"
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```

## Bootstrap server [POST /v3/server/:id/bootstrap]
> Bootstrap server with identifier ':id'

### Request
  * Policy: deploy_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json
    *  X-Stream: true -> return output in text stream

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server_id",
  "cm_name": "server cm name",
  "message" : "Bootstraped"
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```

## Unbootstrap server [POST /v3/server/:id/unbootstrap]
> Unbootstrap server with identifier ':id'

### Request
  * Policy: deploy_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server_id",
  "message" : "Unbootstraped"
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```

## Deploy server [POST /v3/server/:id/deploy]
> Deploy server with identifier ':id'

### Request
  * Policy: deploy_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json
    *  X-Stream: true -> return output in text stream
  * Body:
```json
{
  "tags": [],         -> array of tags to apply on each server before running chef-client
  "build_number": "", -> string, build number to deploy
  "run_list": [],     -> array of strings to set run_list for chef-client
}
```

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server id",
  "message": ""
}
```

**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```

## Add server [POST /v3/server/add]
> Add external server

### Request
  * Policy: create_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json
  * Body:
```json
{
  "project": "project id",    -> mandatory parameter
  "environment": "env id",    -> mandatory parameter
  "category": "category id",  -> mandatory parameter
  "key": "ssh key",           -> mandatory parameter
  "remote_user": "ssh user",  -> mandatory parameter
  "private_ip": "ip",         -> mandatory parameter
  "public_ip": "ip"
}
```

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server_id",
  "message" : "Added"
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```

## Add server tags [POST /v3/server/:id/tags/add]
> Add cloud server tags

### Request
  * Policy: create_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json
  * Body:
```json
{
  "tags": [
    {"tag name": "tag value"}
  ]
}
```

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server_id",
  "message" : "Added"
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```

## Delete server tags [POST /v3/server/:id/tags/delete]
> Delete cloud server tags

### Request
  * Policy: create_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json
  * Body:
```json
{
  "tags": [
    {"tag name": "tag value"}
  ]
}
```

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server_id",
  "message" : "Deleted"
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```

## Set server run list [POST /v3/server/:id/run_list]
> Set server run list

### Request
  * Policy: create_server
  * Method: POST
  * Headers:
    *  Accept: application/json
    *  Content-Type: application/json
  * Body:
```json
{
  "run_list": [
  ]
}
```

### Response
**Status: 200**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "id": "server_id",
  "message" : "Deleted"
}
```
**Status: 404**
  * Headers:
    *  Content-Type: application/json
  * Body:
```json
{
  "message": ""
}
```