How to create a dedicated server via public API

Introduction

This guide provides instructions on configuring and ordering a server using the API. For this example, we’re looking at the Dell R220 / Intel Xeon E3-1231 v3 / 32 GB RAM / 2x480 GB SSD server in the AMS1 location. To explore other available server models, configurations and locations, please visit the customer portal.

You can use either a password or an SSH key to authenticate a server. All SSH key fingerprints can be found in the customer portal in the Identity and Access → SSH & GPG keys section. Filling in user information is optional.

As you proceed with the requests, use the IDs obtained in the previous steps. Examples of requests and instructions on setting parameters will be provided in each section.

Environment setup

Before you start working with the API, you need to set up your environment for making requests. This includes installing the necessary tools that will be used for authentication and making API requests.

Most modern operating systems come with built-in command-line tools like cURL. Additionally, you can use other tools to work with APIs:

• Graphical tools like Postman can simplify sending API requests and receiving server responses

• Some modern IDEs (Integrated Development Environments) have plugins or built-in tools for working with APIs (e.g., Visual Studio Code and JetBrains IDEs)

Once your environment is set up, you are ready to start working with the API. You can make requests, and will receive responses from the server.

Authentication

All requests to the public API must include your authentication token and must be made using cURL, as specified in the Public API documentation.

To get an API token, complete the following steps:

1. Go to the customer portal

2. In the left-hand menu, navigate to Identity and Access and select API keys

3. Click Create

4. Specify the name of the API key and select Read & Write permissions

5. Click Create

An API token will be generated. To send authorized requests, replace TOKEN with your API token in each request.

Getting a list of available locations

Before finding the required server and its ID, you must first get a list of available locations and choose the desired one from the list.

To get the list of locations, execute the following GET request:

curl -g "https://api.servers.com/v1/locations" -X GET \ -H "Authorization: Bearer TOKEN"

View the request/response details in the Public API documentation

As an example, the required location AMS1 (Amsterdam Metropolitan Area, The Netherlands) has id: 1.

Getting a list of available dedicated servers in the selected location

In the request body, specify the following parameters:

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/server_models" -X GET \ -H "Authorization: Bearer TOKEN"

View the request/response details in the Public API documentation

The response will include a list of available servers and their configurations for the selected location.

For custom configurations, all necessary parameters can be specified in the request body. For more details, see: Create a dedicated server.

In the list of server models, the required server model has ID: 10522.

Configuring the selected server

Before configuring and ordering the server, you will need to perform several GET requests to retrieve some required IDs and parameters, such as uplink_models, bandwidth_id, drives, and more.

Getting the list of uplinks

In the request body, specify the following parameters:

To get the list of uplinks available for a specific server model and their IDs, execute the following GET request:

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/server_models/{server_model_id}/uplink_models" -X GET \ -H "Authorization: Bearer {TOKEN}"

View the request/response details in the Public API documentation

Based on the response, let's choose for example:

• Private 1 Gbps without redundancy has ID: 10201

• Public 1 Gbps without redundancy has ID: 10198

Getting available bandwidths for public uplink

In the request body, specify the following parameters:

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/_models/{server_model_id}/uplink_models/{uplink_model_id}/bandwidth" -X GET \ -H "Authorization: Bearer TOKEN"

View the request/response details in the Public API documentation

The bandwidth has ID: 13744.

Selecting the RAM size

Select the RAM size based on the range of ram and max_ram parameters provided in the response for the selected server configuration.

In the request body, specify the following parameters:

To retrieve this information, execute the following GET request:

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/server_models/{server_model_id}/ram" -X GET \ -H "Authorization: Bearer TOKEN"

View the request/response details in the Public API documentation

Based on the ram and max_ram parameters in the response, the selected server has a fixed memory size of 32 GB.

Getting disk models

At this step, you need to determine which disks will be installed and in which slots.

In the request body, specify the following parameters:

To get a list of available disk models for the selected server model, execute the following GET request:

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/server_models/{server_model_id}/drive_models" -X GET \ -H "Authorization: Bearer TOKEN"

View the request/response details in the Public API documentation

Based on the response, let's use as an example two `2 TB SATA3 HDDs`, which has ID: 10306, which will be mounted in each slot.

Disk partitioning

For this example, we will choose a simple disk partitioning setup with software RAID 0. The server model chosen for this example does not have a hardware RAID controller.

Getting the list of available operating systems

In the request body, specify the following parameters:

To get a list of operating systems available for installation and their IDs, execute the following GET request:

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/server_models/{server_model_id}/operating_systems" -X GET \ -H "Authorization: Bearer TOKEN"

View the request/response details in the Public API documentation

Based on the response, let's use as an example `Ubuntu 20.04-server x86_64`ID: 49.

Now that all parameters have been defined, you can form the cURL request to configure your server.

Ordering a server

In the request body, specify the following parameters:

To order a server, execute the following POST request:

curl "https://api.servers.com/v1/hosts/dedicated_servers" -d '{
  "server_model_id": {server_model_id},
  "location_id": {location_id},
  "ram_size": {ram_size},
  "uplink_models": {
    "public": {
      "id": {public_uplink_id},
      "bandwidth_model_id": {bandwidth_id}
    },
    "private": {
      "id": {private_uplink_id}
    }
  },
  "drives": {
    "slots": [
      {
        "position": {position_num},
        "drive_model_id": {drive_id}
      },
      {
        "position": {position_num},
        "drive_model_id": {drive_id}
      }
    ],
    "layout": [
      {
        "slot_positions": [
          {position_num},
          {position_num}
        ],
        "raid": {raid_level},
        "partitions": [
          {
            "target": "/boot",
            "size": {boot_partition_size},
            "fill": false,
            "fs": "ext4"
          },
          {
            "target": "swap",
            "size": {swap_partition_size},
            "fill": false
          },
          {
            "target": "/",
            "size": {root_partition_size},
            "fill": true,
            "fs": "ext4"
          }
        ]
      }
    ]
  },
  "ipv6": false,
  "hosts": [
    {
      "hostname": "{hostname}"
    }
  ],
  "operating_system_id": {operating_system_id}
}' -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer TOKEN"

View the request/response details in the Public API documentation

If successful, you will receive a response from the server containing the order details and the ID of the newly created server. If there are any issues with the request, error messages will be displayed in the console.

Checking the status of a created server

In the request body, specify the following parameters:

You can also find the server ID in the customer portal:

1. Go to the customer portal

2. In the left-hand menu, navigate to Dedicated Servers → Manage

3. Find the dedicated server by its name and click Details

To check the status and activity of the server, make the following request:

curl -g "https://api.servers.com/v1/hosts/dedicated_servers/{server_id}" -X GET \ -H "Authorization: Bearer TOKEN"

View the request/response details in the Public API documentation