Developer Area

Cloud Server Shared CPU API

Introduction

Cloud Server Shared CPU is the on demand cloud service ideal for testing, development, staging and for who needs to create and destroy per-per-use cloud machines quickly and with cost optimization.

API Authentication

To start with the API services, you need to authenticate your request with an access token. This token will be available after the validation of your credential.

To get the access token, send a POST request to /ecs/v2/login.

Parameter Description
username The same username that you use to login to the control panel
password The same value as that of the control panel

Request

                curl -X POST https://api.seeweb.it/ecs/v2/login \
                  -F username=<your_username> \
                  -F password=<your_password>

Response

                {
                  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY2NTA5MTYsIm5iZiI6MTU1NjYzNjUxNiwidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.HzkQs3hTU7RuUljFcD513bkaAqJvH9TmaAlocT13T84",
                  "expire": 1556650916,
                  "status": "ok"
                }

Server

Cloud Server is a KVM virtual machine. It can be created in a few minutes and in a very easy way. The panel allows you to install it on different regions. When creating a new server, you can select your favorite Operating System and size. In fact, multiple plans are available.

Create New Server

To create a new server, send a POST request to /ecs/v2/servers.

The attribute values that must be set to successfully create a Server are:

Name Type Description Required
plan string the server plan true
location string location identifier true
image string The image name of a public or private template true
notes string The human-readable string you wish to use to display server name true
ssh_key string Public key label false

Request

                curl -X POST https://api.seeweb.it/ecs/v2/servers \
                  -H 'Content-Type: application/json' \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY2NTA5MTYsIm5iZiI6MTU1NjYzNjUxNiwidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.HzkQs3hTU7RuUljFcD513bkaAqJvH9TmaAlocT13T84' \
                  -d '{
                        "plan": "ECS1",
                        "location":"it-fr2",
                        "image": "centos-7",
                        "notes": "my first server"
                        "ssh_key": "public_key_label"
                  }'

Response

                {
                  "status": "ok",
                  "action_id": 38,
                  "server": {
                    "name": "ec200016",
                    "ipv4": "",
                    "ipv6": "",
                    "plan": "ECS1",
                    "plan_size": {
                      "core": "1",
                      "ram": "1024",
                      "disk": "20"
                    },
                    "location": "it-fr2",
                    "notes": "my first server",
                    "so": "centos-7",
                    "creation_date": "2019-04-30T15:19:48.535586+00:00",
                    "deletion_date": null,
                    "active_flag": false,
                    "status": "Booting",
                    "api_version": "v4",
                    "user": "admin"
                  }
                }

List All Servers

To retrieve all the server information, send a GET request to /ecs/v2/servers.

The response body will be a JSON object with the number of servers and an array that contains the server objects. A server object contains these attributes:

Name Type Description
name string An unique identifier for each server
ipv4 string The server public IPv4
ipv6 string The server public IPv6
plan string The current server plan
plan_size object The server plan configuration sizes
location string An unique identifier for the server region
notes string A human-readable name for this server
so string The template image used to deploy this server
creation_date string A time value given in ISO8601 combined date and time format that represents when the server was created
deletion_date string A time value given in ISO8601 combined date and time format that represents when the server was deleted
active_flag bool A flag value that shows if the server is active
status string The server status: Booted, Booting, Deleting, Deleted
api_version string The server API version
user string The server account username
virttype string The virtualization engine name

Request

                curl -X GET https://api.seeweb.it/ecs/v2/servers \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY2NTA5MTYsIm5iZiI6MTU1NjYzNjUxNiwidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.HzkQs3hTU7RuUljFcD513bkaAqJvH9TmaAlocT13T84'

Response

                {
                  "status": "ok",
                  "count": 4,
                  "server": [
                    {
                      "name": "ec200016",
                      "ipv4": "192.168.1.43",
                      "ipv6": "fe80::1",
                      "plan": "ECS1",
                      "plan_size": {
                        "core": "1",
                        "ram": "1024",
                        "disk": "20"
                      },
                      "location": "it-fr2",
                      "notes": "my first server",
                      "so": "centos-7",
                      "creation_date": "2019-04-18T13:48:12.025548+00:00",
                      "deletion_date": null,
                      "active_flag": true,
                      "status": "Booted",
                      "api_version": "v4",
                      "user": "admin",
                      "virttype": "KVM"
                    },
                    ...
                  ]
                }

Update Server Information

To update server information such as notes or group, send a PUT request to /ecs/v2/servers/$SERVER_NAME.

The attribute values that can be set to successfully update a Server information are:

Name Type Description
note string A human-readable name for this server
group string The group name where the server belongs

Request

                curl -X PUT https://api.seeweb.it/ecs/v2/servers/$SERVER_NAME \
                  -H 'Content-Type: application/json' \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY2NTA5MTYsIm5iZiI6MTU1NjYzNjUxNiwidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.HzkQs3hTU7RuUljFcD513bkaAqJvH9TmaAlocT13T84' \
                  -d '{
                       "note": "update server name",
                       "group": "eg103464"
                  }'

Response

                {
                  "status":"ok"
                }

Delete a Server

To delete a Server, send a DELETE request to /ecs/v2/servers/$SERVER_NAME.

The response body will contain:

Response

                {
                  "status": "ok",
                  "action": {
                    "id": 39,
                    "status": "in-progress",
                    "user": "admin",
                    "created_at": "2019-04-30T16:33:03.317800+00:00",
                    "started_at": "2019-04-30T16:33:03.317019+00:00",
                    "completed_at": null,
                    "resource": "ec200016",
                    "resource_type": "ECS",
                    "type": "delete_server",
                    "progress": 0
                  }
                }

Server Status

To get the real server VM status, send a GET request to _/ecs/v2/servers/$SERVER_NAME/status.

Response

                {
                  "status": "ok",
                  "name": "ec200016",
                  "current_status": "RUNNING"
                }

Server Console

To get the console token for a server, send a POST request to /ecs/v2/servers/$SERVER_NAME/actions.

The console token must be used to connect to the server console API.

Request

                curl -X POST https://api.seeweb.it/ecs/v2/servers/$SERVER_NAME/actions \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY2NTA5MTYsIm5iZiI6MTU1NjYzNjUxNiwidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.HzkQs3hTU7RuUljFcD513bkaAqJvH9TmaAlocT13T84' \
                  -H 'Content-Type: application/json' \
                  -d '{
                      "type":"console"
                  }'

Response

                {
                  "action": {
                    "id": 40,
                    "status": "in-progress",
                    "user": "admin",
                    "created_at": "2019-04-30T17:13:55.791056+00:00",
                    "started_at": "2019-04-30T17:13:55.790263+00:00",
                    "completed_at": null,
                    "resource": "ec200016",
                    "resource_type": "ECS",
                    "type": "console",
                    "progress": 0
                  },
                  "console_key": "4bd4c166-f31a-4d5d-8c88-5a16273f033b"
                }

Server power-cycle

The power cycle actions for a server is the same for the console, but with differ the action type string.

The available action type are:

Action Type Description
power_on Start and booting an Cloud Server
power_off Shutdown an Cloud Server

Request

                curl -X POST https://api.seeweb.it/ecs/v2/servers/$SERVER_NAME/actions \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY2NTA5MTYsIm5iZiI6MTU1NjYzNjUxNiwidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.HzkQs3hTU7RuUljFcD513bkaAqJvH9TmaAlocT13T84' \
                  -H 'Content-Type: application/json' \
                  -d '{
                    "type":"power_on"
                  }'

Response

                {
                  "action": {
                    "id": 40,
                    "status": "in-progress",
                    "user": "admin",
                    "created_at": "2019-04-30T17:13:55.791056+00:00",
                    "started_at": "2019-04-30T17:13:55.790263+00:00",
                    "completed_at": null,
                    "resource": "ec200016",
                    "resource_type": "ECS",
                    "type": "power_on",
                    "progress": 0
                  }
                }

Server Metrics

To retrieve the metrics of a Server, send a GET request to _/ecs/v2/servers/$SERVER_NAME/metrics.

Request params:

Name Type Description
start string An ISO8601 date that represents when the statistics data starts
end string An ISO8601 date that represents when the statistics data ends

Request

                curl -X GET https://api.seeweb.it/ecs/v2/servers/ec200016/metrics \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY4MDQyMDcsIm5iZiI6MTU1Njc4OTgwNywidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.sbTUNFHc0mY9yTrMKN0x13UOZrYSU520txocUHLIsM4'

Response

                {
                  "metrics": {
                    "core": [
                      [
                        1551088373.819,
                        "1.0333290277955356"
                      ],
                      [
                        1551090173.819,
                        "1.4000000000002426"
                      ],
                    ],
                    "disk": {
                      "writes": [
                        [
                          1551088373.819,
                          "0.14999937500260416"
                        ],
                        [
                          1551090173.819,
                          "0.15833333333333333"
                        ],
                      ],
                      "reads": [
                        [
                          1551088373.819,
                          "0"
                        ],
                        [
                          1551090173.819,
                          "0"
                        ],
                      ],
                    },
                    "resource": "ec200016",
                    "network": {
                      "received": [
                        [
                          1551088373.819,
                          "125.52864363065154"
                        ],
                        [
                          1551090173.819,
                          "93.74166666666666"
                        ],
                      ],
                      "transmitted": [
                        [
                          1551088373.819,
                          "180.90757955175187"
                        ],
                        [
                          1551090173.819,
                          "136.925"
                        ],
                      ]
                    }
                  }
                }

Actions

Actions are records of events that have occurred on the resources in your account.

An action object is created every time one of these actions is initiated. The action object contains informations about the current status of the action, start and complete timestamps, and the associated resource type and ID.

Every action that creates an action object is available through this endpoint. Completed actions are not removed from this list and are always available for querying.

Name Type Description
status string The current status of the action. This can be "in-progress", "completed", or "error"
resource string A unique identifier for the resource that the action is associated with
user string A unique identifier for the account that the action is associated with
created_at string A time value given in ISO8601 combined date and time format that represents when the action was created
started_at string A time value given in ISO8601 combined date and time format that represents when the action was initiated
completed_at string A time value given in ISO8601 combined date and time format that represents when the action was completed
type string This is the type of action that the object represents
id integer A unique numeric ID that can be used to identify and reference an action
resource_type string The type of resource that the action is associated with
progress integer A value that represent the percentage of completation

List All Actions

To list all actions, send a GET request to /ecs/v2/actions.

Request

                curl -X GET https://api.seeweb.it/ecs/v2/actions \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY4MDQyMDcsIm5iZiI6MTU1Njc4OTgwNywidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.sbTUNFHc0mY9yTrMKN0x13UOZrYSU520txocUHLIsM4'

Response

                {
                  "status": "ok",
                  "actions": [
                    {
                      "id": 39,
                      "status": "completed",
                      "user": "admin",
                      "created_at": "2019-04-30T16:33:03.317800+00:00",
                      "started_at": "2019-04-30T16:33:03.317019+00:00",
                      "completed_at": "2019-04-30T16:34:04.159922+00:00",
                      "resource": "ec200016",
                      "resource_type": "ECS",
                      "type": "delete_server",
                      "progress": 100
                    },
                    {
                      "id": 38,
                      "status": "completed",
                      "user": "admin",
                      "created_at": "2019-04-30T15:19:48.539503+00:00",
                      "started_at": "2019-04-30T15:19:48.534100+00:00",
                      "completed_at": "2019-04-30T15:20:10.112664+00:00",
                      "resource": "ec200016",
                      "resource_type": "ECS",
                      "type": "create_server",
                      "progress": 100
                    },
                  ]
                }

Retrieve a specific Action

To retrieve a specific action, send a GET request to /ecs/v2/actions/$ACTION_ID.

Request

                curl -X GET https://api.seeweb.it/ecs/v2/actions/39 \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY4MDQyMDcsIm5iZiI6MTU1Njc4OTgwNywidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.sbTUNFHc0mY9yTrMKN0x13UOZrYSU520txocUHLIsM4'

Response

                {
                  "status": "ok",
                  "action": {
                    "id": 39,
                    "status": "completed",
                    "user": "admin",
                    "created_at": "2019-04-30T16:33:03.317800+00:00",
                    "started_at": "2019-04-30T16:33:03.317019+00:00",
                    "completed_at": "2019-04-30T16:34:04.159922+00:00",
                    "resource": "ec200016",
                    "resource_type": "ECS",
                    "type": "delete_server",
                    "progress": 100
                  }
                }

Templates

Templates are saved instances of a server.

To interact with templates, you will generally send requests to the template endpoint at /ecs/v2/templates.

Name Type Description
id integer A unique numeric ID that can be used to identify and reference a template
name string A unique template name
creation_date string A time value given in ISO8601 combined date and time format that represents when the template was created
active_flag bool A flag that represents if a template is manageble
status string The current status of the template. This can be "Creating", "Created", "Deleting" or "Deleted"
uuid string A unique identifier
notes string A human-readable friendly description

List all Templates

To list all templates, send a GET request to /ecs/v2/templates.

Request

                curl -X GET https://api.seeweb.it/ecs/v2/templates \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY4MDQyMDcsIm5iZiI6MTU1Njc4OTgwNywidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.sbTUNFHc0mY9yTrMKN0x13UOZrYSU520txocUHLIsM4'

Response

                {
                  "status": "ok",
                  "templates": [
                    {
                      "id": 9,
                      "name": "ei100006",
                      "creation_date": "2019-04-24T11:12:44.121251+00:00",
                      "active_flag": true,
                      "status": "Created",
                      "uuid": "6e71411b-5c94-202c-c4fc-bacd3c864b1b",
                      "notes": "Template server staging"
                    },
                    {
                      "id": 10,
                      "name": "ei100007",
                      "creation_date": "2019-04-24T11:28:58.821111+00:00",
                      "active_flag": true,
                      "status": "Created",
                      "uuid": "b3f8115b-1090-0173-b37e-b27685bd9dfc",
                      "notes": "Template server produzione"
                    }
                  ]
                }

Retrieve a specific Template

To retrieve a specific template, send a GET request to /ecs/v2/templates/$TEMPLATE_ID.

Request

                curl -X GET https://api.seeweb.it/ecs/v2/templates/9 \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY4MDQyMDcsIm5iZiI6MTU1Njc4OTgwNywidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.sbTUNFHc0mY9yTrMKN0x13UOZrYSU520txocUHLIsM4'

Response

                {
                  "status": "ok",
                  "template": {
                    "id": 9,
                    "name": "ei100006",
                    "creation_date": "2019-04-24T11:12:44.121251+00:00",
                    "active_flag": true,
                    "status": "Created",
                    "uuid": "6e71411b-5c94-202c-c4fc-bacd3c864b1b",
                    "notes": "Template server staging"
                  }
                }

Delete a Template

To delete a template, send a DELETE request to /ecs/v2/templates/$TEMPLATE_ID.

Response

                {
                  "status": "ok",
                  "action": {
                    "id": 41,
                    "status": "in-progress",
                    "user": "admin",
                    "created_at": "2019-05-02T10:57:19.814908+00:00",
                    "started_at": "2019-05-02T10:57:19.814151+00:00",
                    "completed_at": null,
                    "resource": "ei100006",
                    "resource_type": "ECI",
                    "type": "delete_template",
                    "progress": 0
                  }
                }

Groups

A Group is a label that can be applied to a server in order to better organize your infrastructure.

Group have three attributes:

Name Type Description
id integer A unique number ID
name string A unique group name
notes string A human-readable friendly description
enabled bool The current status of a group

Create a new Group

To create a new group, send a POST request to /ecs/v2/groups.

The required attributes are:

Name Type Description
notes string A human-readable friendly description
password string A private password used to make a subview of the infrastructure

Request

                curl -X POST https://api.seeweb.it/ecs/v2/groups \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY4MDQyMDcsIm5iZiI6MTU1Njc4OTgwNywidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.sbTUNFHc0mY9yTrMKN0x13UOZrYSU520txocUHLIsM4' \
                  -d '{
                    "notes": "Test group 1",
                    "password": "secret"
                  }'

Response

                {
                  "status": "ok",
                  "group": {
                    "id": 2,
                    "name": "eg100001",
                    "notes": "Test group 1",
                    "enabled": true
                  }
                }

List all Groups

To list all groups, send a GET request to /ecs/v2/groups

Request

                curl -X GET https://api.seeweb.it/ecs/v2/groups \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY4MDQyMDcsIm5iZiI6MTU1Njc4OTgwNywidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.sbTUNFHc0mY9yTrMKN0x13UOZrYSU520txocUHLIsM4'

Response

                {
                  "status": "ok",
                  "groups": [
                    {
                      "id": 2,
                      "name": "eg100001",
                      "notes": "Test group 1",
                      "enabled": true
                    }
                  ]
                }

Delete Group

To delete a group, send a DELETE request to /ecs/v2/groups/$GROUP_ID.

Response

                {
                  "status": "ok"
                }

Regions

A region is the datacenter where your servers can be deployed.

Each region represents a specific datafarm in a geographic location. Some locations may offer multiple "regions". This means that there are multiple datacenters available in a single area.

List all Regions

To list all regions, send a GET request to /ecs/v2/regions

Request

                curl -X GET https://api.seeweb.it/ecs/v2/regions \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY4MDQyMDcsIm5iZiI6MTU1Njc4OTgwNywidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.sbTUNFHc0mY9yTrMKN0x13UOZrYSU520txocUHLIsM4'

Response

                {
                    "status": "ok",
                    "regions": [
                      {
                        "id": 1,
                        "location": "it-fr2",
                        "description": "Frosinone"
                      }
                    ]
                }

Plans

A plan is a specific configuration available. You can choose among different plans, depending on the power you need.

List all Plans

To list all plans, send a GET request to /ecs/v2/plans.

Request

                curl -X GET https://api.seeweb.it/ecs/v2/plans \
                  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTY4MDQyMDcsIm5iZiI6MTU1Njc4OTgwNywidXNlcm5hbWUiOiJhZG1pbiIsImVtYWlsIjoiZGFuaWVsZXZAc2Vld2ViLml0In0.sbTUNFHc0mY9yTrMKN0x13UOZrYSU520txocUHLIsM4'

Response

                {
                  "status": "ok",
                  "plans": [
                    {
                      "id": 1,
                      "name": "ECS1",
                      "cpu": "1",
                      "ram": "1024",
                      "disk": "20",
                      "hourly_price": 0.017,
                      "montly_price": 12,
                      "windows": false,
                      "available": true,
                      "available_regions": [
                        {
                          "id": 1,
                          "location": "it-fr2",
                          "description": "Frosinone"
                        }
                      ]
                    },
                    ...
                  ]
                }