How to create a server with the Clouding API

An API (Application Programming Interface) is a program that allows different applications to communicate with each other to share information and functionalities.

In this sense, our API allows you to manage everything you can do in the Clouding panel. From creating servers from different sources, to archiving/unarchiving, creating snapshots, activating backups, adding firewall rules, etc.

To create the server in this tutorial we will use the CURL command. By default, CURL is installed on most Linux and Mac. If you are using Windows you can follow our tutorial on how to install CURL on Windows.

Before you start

In order to perform this tutorial you will need access to an API-KEY. To get an API-KEY you will need to contact our support team. At this moment the API is in a private beta phase, that's why if you want to test it you should contact us.

Create a server using CURL

To create a server using CURL it is necessary to execute the following command with all this structure:

NOTE: The commands used are with the required parameters, for more information you can check the official Clouding API documentation.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-API-KEY: $CLOUDING_APIKEY" \
-d '{"name":"Nombre Servidor","hostname":"server.hostname.com","flavorId":"2x4","firewallId":"$FIREWALLID","accessConfiguration":{"password":"contraseña","savePassword":true,"sshKeyId":"$SSHKEYID"},"volume":{"source":"Image","id":"$VOLUMEID","ssdGb":10}}' \
"https://api.clouding.io/v1/servers"    

In order to execute this command correctly you will need to obtain the following parameters:

• name: the name server.
• hostname: the hostname server.
• flavorId: corresponds to the vcores and gigabytes in RAM. For example, 2x4 corresponds to 2vcores and 4GB of RAM. You can visualize all the options using the flavors endpoint. You can visualize all the options with the following command in CURL:
  

  curl -X GET -H "Content-Type: application/json" -H "X-API-KEY: $CLOUDING_APIKEY" "https://api.clouding.io/v1/sizes/flavors?page=1&pageSize=20"

• firewallid: to create a server you have to assign a firewall, so you will have to add the id of the firewall you want to attach to our server. To list all the firewalls in our account:
  

  curl -X GET -H "Content-Type: application/json" -H "X-API-KEY: $CLOUDING_APIKEY" "https://api.clouding.io/v1/firewalls?page=1&pageSize=20"

• accessConfiguration: In this section you must configure different parameters, among them the password.

   Important

  If the server contains QEMU-AGENT, you will be able to select a password, otherwise the password must be empty or null.

  Then you have savePassword if you want to save the password in the panel and the sshkeyId corresponding to the SSH key.
  To list all SSH keys:savePassword if you want to save the password in the panel and the keyParId corresponding to the SSH key.
  To list all SSH keys:

  curl -X GET -H "Content-Type: application/json" -H "X-API-KEY: $CLOUDING_APIKEY" "https://api.clouding.io/v1/keypairs?page=1&pageSize=20"

   

• volume: This is the server disk configuration. You must select the source that can be "image", "backup", "snapshot" or "server". In this case you will select the image option. Then you will have to add the volume ID, in this case to list all the available images:
  

  curl -X GET -H "Content-Type: application/json" -H "X-API-KEY: $CLOUDING_APIKEY" "https://api.clouding.io/v1/images?page=1&pageSize=20"

  Finally you will choose the parameter ssdGb which corresponds to the size of the disk in GB.

Check process status

When you execute the request to create a new server to the Clouding API, the API response is as follows:

{
  "id": "q1ZJVKX8bW0KkY6p",
  "name": "Nombre del Servidor",
  "hostname": "server.hostname.com",
  "vCores": 1,
  "ramGb": 2,
  "flavor": "1x2",
  "volumeSizeGb": 10,
  "image": {
    "id": "BJebl0d7zA2WGwQ1",
    "name": "Debian 11 (64 Bit)"
  },
  "status": "Pending",
  "pendingFeatures": [],
  "pendingFirewalls": [
    "p06Wq42PvbKeDVEb"
  ],
  "requestedAccessConfiguration": {
    "sshKeyId": "X19wGdRz0xdPlJbg",
    "hasPassword": false,
    "savePassword": false
  },
  "backupPreferences": null,
  "action": {
    "id": "gNMqlnNpQ0xd7pyk",
    "status": "inProgress",
    "type": "create",
    "startedAt": "2023-02-20T15:34:44.9351504Z",
    "completedAt": null,
    "resourceId": "q1ZJVKX8bW0KkY6p",
    "resourceType": "server"
  }
}

If you look at the last property called action, you have some interesting information about the request:

• id: The unique identifier of the action.
• status: Current status of the action. Possible values are: pending, inProgress, completed, error.
• type: The type of action being performed, such as creating a server snapshot. In this case create a server.
• StartedAt: The date and time the action was started, in UTC time.
• completedAt: The date and time the action was completed, in UTC time. This field will be null if the action is still in progress (as it is in this example).
• resourceId: The unique identifier of the resource on which the action is being performed, such as a server.
• resourceType: The type of resource on which the action is being performed, such as a server or snapshot.

As you can see in the example above, this action is in progress but not completed. You can check these actions on a specific endpoint to show you the status or to know if it has finished successfully.

For example, to check the action with the example ID:

  curl -X GET -H "Content-Type: application/json" -H "X-API-KEY: $CLOUDING_APIKEY"
  "https://api.clouding.io/v1/actions/gNMqlnNpQ0xd7pyk"

It will show you the following result:

{
  "id": "gNMqlnNpQ0xd7pyk",
  "status": "completed",
  "type": "create",
  "startedAt": "2023-02-20T15:34:44Z",
  "completedAt": "2023-02-20T15:35:47Z",
  "resourceId": "q1ZJVKX8bW0KkY6p",
  "resourceType": "server"
}

In this case, you will notice that the status right now is completed and that it has a completion date.

We hope we have helped you, have you tried it? Leave us your comments! 🙂 

Remember, if you have any doubts about this article or any other question related to your Clouding servers, write us at support@clouding.io We are at your disposal for anything you need!