API
Using the API, you can manage everything—from organizations and projects to servers, IP addresses, and more—entirely programmatically.
It is possible to control the features of the control panel via an API, enabling automation of many tasks. For example, you can run a script on a VM that uses the API to automatically adjust the number of CPU cores as the load fluctuates. A sample script for this purpose is available on GitHub.
This section serves as a getting-started guide for the Glesys API. The complete API documentation can be found on the Glesys GitHub page.
Create keys
There are two types of API keys: permanent and temporary.
Permanent keys are created in advance and can be used from predefined IP addresses. You also specify the key's permissions before it can be used.
Temporary keys are retrieved by logging in to the API using a username and password. This is the same username and password you use to log in to the control panel in Glesys Cloud. Upon logging in, you receive a list of organizations and projects that the user has access to. These are the same organizations and projects you have granted the user access to under Permissions for collaborator in the control panel. You use these projects or organizations as the username when making API calls. The password is the API key you received when you logged in with your username and password.
You find the page for permanent API keys under your user profile in the control panel. Click on the user icon in the top-right corner and select Control API access.
In the dialog box that appears, click the Create button. In the next dialog box, we enter a name for the key and specify which project it should have access to. In the example image below, we name the key my-test-key and grant it access to the project Lab1. Click Create to generate the key.
By default, new keys have no access from any IP addresses and no permissions to do anything. Start by granting access to the key from an IP address. Click Access in the Actions menu for the key.
Here, enter the IP addresses that should be able to use the API key. It is possible to specify both individual addresses and entire networks. The IP addresses and networks are separated by commas. Hostnames can also be specified. Additionally, access can be granted to all IP addresses by using the network 0.0.0.0/0. However, this should be avoided.
In the example below, only the IP addresses 203.0.113.2, 203.0.113.11, and the network 192.0.2.0/24 can use the key. Click Add to save and add the IP addresses.
After clicking Add, the keys are displayed in the same dialog box under Hosts with access. If everything looks correct, close the dialog box by clicking Close.
In the overview, it now shows how many hosts have access to the key.
Next, you need to grant the key permissions to perform various actions on different types of resources. To do this, click Permissions in the Actions menu for the key.
The permissions for keys are divided into modules. You can choose to grant the key permission to use all modules or restrict it to only the modules that are needed. It is more secure to only grant keys the permissions they genuinely require. Therefore, click Show modules to assign permissions to specific modules.
For each module listed, you can either grant full permissions to that module or specify which functions within the module the key should have permission to use. To display a module's functions, click Show functions next to the module.
In the example below, we have granted the key full permissions for the Server module, meaning the key can perform all functions for servers in the project where the key was created. For the IP module, the key has only specific permissions. Note that the image below is cropped and shows only a portion of the available modules.
Click Save at the bottom of the dialog box to save the key's permissions.
Test the permanent key
You have now created the key, assigned permissions to certain modules, and granted access to the key from specific IP addresses. Now it’s time to test the key.
To test the key, you first need to copy the key's password. In the key's overview, click the icon to copy the key's password. The username for the key is the project; in this example, it is cl43212.
Now, try making an API call using cURL. Keep in mind that the call must be made from an IP address that you have added to the access list.
The URL for the API is https://api.glesys.com. The function we are testing here is /server/list. Note that the key must have permission to use /server/list. We use basic auth for authentication. For security purposes, we disable the shell history first.
The response from the API will look like the example below (note that this is just a brief excerpt of the full output).
Now we know that the key works, and we can re-enable the shell history:
Temporary keys are created by logging into the API using the same username and password you use to log in to the Glesys Cloud control panel. The key created, therefore, has the same permissions as the user logging in to create it. A temporary key expires after six hours of inactivity.
To create a temporary key, start by logging into the API using the /user/login function. As parameters, you must provide the account's username and password. Since you will be entering your account password, start by disabling the shell history. Afterward, you can re-enable the history. Enclose the URL in quotation marks because it contains special characters that the shell would otherwise interpret.
The response includes information about what the user has access to, as well as the key to be used as the password. It might look like the example below (this is just a brief excerpt from a much longer response):
Here, you can see that the user has full permissions for the project cl43212, but only read permissions for the organization 123456.
In the response, you also received the API key, xxx-yyy-zzz-123.
Testing the temporary key
You can now use the project, cl43212, as the username and the API key, xxx-yyy-zzz-123, as the password to make API calls. It is also possible to use the organization number as the username, but in this case, we only have read permissions for the organization. Additionally, the control panel username can be used. Depending on what you use as the username (project, organization, or Cloud account), you gain access to different features.
For example, using the Cloud account as the username provides access to personal account details. Using the project as the username grants access to project-based functions, such as creating, starting, and stopping VMs. Using the organization as the username allows access to organization-wide features, such as invoice management and similar tasks.
Since this user has full access to the project cl43212, we will use it as the username and list all servers. Provide the username and password as basic auth:
The response you receive looks something like the example below (this is just a brief excerpt from a much longer response):
This confirms that the temporary key works.
Some examples
Regardless of the type of key you use, the API works the same way and provides the same functions.
JSON as response type
By default, the API responds with an XML document. If you want the response as a JSON object instead, you need to specify this to the API by including a header in the request. To format the JSON data, you can pipe it to jq (omit jq to get the raw JSON data):
The response you receive looks something like the example below (this is just a brief excerpt from a much longer response):
Update a PTR record
For functions that require arguments, you specify these as parameters in standard URL format. For example, to update the PTR record for an IP address, you provide the IP address and the fully qualified domain name (FQDN) as parameters to the /ip/setptr function:
The response indicates whether the update was successful. The output below is just a brief excerpt.
Example with Python
To list all servers using Python, you can create a short script like the one below. We name it glesys-api.py.
Execute the script:
An excerpt from the output is shown here:
Viewing the built-in API documentation
It's possible to view the API documentation by making calls to the API. This way, you can drill down to the specific endpoint you need.
For example, by making a POST or GET request to https://api.glesys.com/ you'll get a list of all available modules.
This will return a 404 error, but will print out a list of all available modules.
You can now make another request to a module of interest, for example, the object storage module.
This will now result in another 404 error, but this time it will return all the information about the module's available functions and their required and optional arguments. The example below is just a short snippet of a much longer output.
Last updated
Was this helpful?