Skip to content

API Introduction

Jump to bottom
Martin Bagge / brother edited this page Sep 22, 2023 · 22 revisions

Introduction to GleSYS API

Background and introduction

The purpose of the GleSYS API (application programming interface) is to allow our customers to access their services and make changes from any script. We don't want our API to be a limited subset of functions compared to our control panel. If you can do it on cloud.glesys.com, you should be able to do it through api.glesys.com. We are not fully there yet but we are working hard on getting there.

Please let us know if you find any bugs or if you have any suggestions on how we can improve our API or our Control Panel.

We are also looking for examples that we can publish in our examples repository here on github. It can be anything from a one-liner to an full-fledged control panel. Please send any examples, feedback or suggestions to support@glesys.se. There might be some good discounts in it for you!

Authentication / Authorization

There are two ways of authenticating against the GleSYS API:

  1. Permanent API key - The permanent API key is a precreated password key for a cloud account and its customer. It has a configurable list of hosts that are allowed to used it and a list of functions that it is allowed to be used for.
  2. Temporary key - The solution with a temporary key works by first logging into the API to get the temporary key and then send a context and this key to the api on any following calls.

The three different types of contexts (as provided by the login with a temporary key) are:

  1. username - has permissions to user specific functions like editing the user details. This represents your personal user.
  2. customernumber - has permission to customer specific functions like invoicing and contact information.
  3. account - a cloud account has permission to functions that handle servers, domains, IPs and more.

Permanent API key

An API key is created for a cloud account and its customer. You can create and mange your API keys in the the control panel API keys page. Each key has a list of hosts that are allowed to use the key. Only these hosts can use the key. You can supply an IP address, an IP range or a hostname for the host.

Examples:

192.0.2.7
192.0.2.0/24
workstation.example.com

You also have to specify which API functions that are allowed to be accessed with the key. This makes it possible to create a key that only has access to a part of the available functions. For example to start, stop or restart a server. It is a good practice to restrict your API keys as much as possible.

Please observe that the default settings for an API key is denied access to all functions for all hosts. You have to change this after you create the key in order to use it.

You can now execute API calls, using HTTP authentication, with a cloud account as username and the API key as password.

Temporary key

A temporary key is generated by logging in against the api with a username and password by using the user/login function. The documentation for this function can be found here. The API responds with a list of cloud projects and customer numbers that the user has permissions to access. When calling the API, these cloud projects (clXXX), customer numbers (XXX) or the username (user@example.com) of the user can be provided as the username in the API call to set the context of the call. One temporary key can therefore be used to list servers on multiple different cloud projects, by changing which cloud project is sent to the API as the username.

The username used for logging in can either be an email address or, for older users, a cloud project key. More information about this can be found in the Backwards compatibility section

To sum up:

  1. Call the user/login function.
  2. Find a list of the username, projects and customer numbers together with the temporary key.
  3. Use the username, the project key or the customer number as the username and the temporary key in the HTTP authentication to make other calls to the api.

Example:

Get a token by calling the user/login function. Send username=test@example.com&password=mypassword12 as POST data.

The following data will be returned:

...
"login": {
      "username": "test@example.com",
      "apikey": "8e729..4f974b",
      "accounts": [
        {
          "account": "cl12345",
          "description": "My own projects"
        },
        {
          "account": "cl98765",
          "description": "Work"
        }
      ],
      "customers": [
        {
          "customernumber": "12345",
          "description": "Private"
        }
      ]
}
...

(The example has been shortened.)

This customer has access to two cloud projects; one for their own personal projects and one for the company they work for.

They also has access to one customer. In this case it is the customer that owns the cloud account where they have their personal projects. The user does not have access to the customer of the company they work for.

The user can now execute API calls, using HTTP authentication, with a username and the token as password:

  • cl98765:8e729..4f974b@server/list - Lists all servers on cl98765
  • cl12345:8e729..4f974b@domain/list - Lists all domains on cl12345
  • 12345:8e729..4f974b@invoice/list - Lists all invoices on the customer 12345
  • test@example.com:8e729..4f974b@user/enabletwofactor - Enables two factor authentication on the user login test@example.com

Contexts

As you can see in the examples above, the username will be used to define the context of the API call. If you have access to multiple cloud accounts and you want to list all servers from one of these accounts, you need to set this account as the username and the temporary key as password. The temporary key generated by user/login is valid for all contexts that you have access to.

Depending on if you send a username, customername or a cloud account as the username in the http authentication you will have access to different functions in the API. The documentation for each API module (for example user or server) will list what kind of authorization is required for that function.

A general overview:

  • customer: invoice and customer modules
  • user: payment card and user modules
  • cloud account: almost everything else

Please look at the API documentation for full details.

Anonymous authentication

Some modules in the API can be accessed anonymously. No authentication needs to be supplied for these.

These are:

  • changelog
  • api

The changelog and api modules are for information purposes, such as service problems and changelogs for the API. If authentication is supplied when calling these function, the authentication will be ignored, as it is not required.

Backwards compatibility

We previously used cloud accounts directly for logging in to our control panel and API. We have since then worked on improving this by adding real users. This means that multiple persons can access the same cloud account and have twofactor authentication, payment cards and more, independent from each other. It also means that you won’t have to log in and out of different cloud accounts to manage all your GleSYS services.

To stay backwards compatible we have migrated all our previous cloud account logins to user logins. These work exactly as a regular login (where an email address is the username). These user logins uses the cloud account name as the username and the password that was previously set on the cloud account as the password. These users have access to their own cloud account and customer. We will provide functionality in our controlpanel to help you converting this cloud account based login to a real, emailaddress based, login.

API documentation

The documentation for all API functions is automatically generated and delivered by a call to the API. More information on how to access the documentation this way is available in the Construction of API calls section.

If you feel that anything is missing or unclear in this documentation, please let us know by sending an email to support@glesys.se.

Introduction to GleSYS API

This document.

Examples

In our examples repository on github we are trying to build a collection of examples that you can use directly or modify to fit your needs. If you write a script that uses our API, please consider sharing it. We reward examples with discounts!

RESTful (Not really)

All calls to GleSYS API are made through the HTTP protocol. The supported methods are POST and GET. All calls support POST but not all support GET. It is insecure to send passwords and other sensitive information in URLs so functions that need this type of information doesn't support GET. For a full list of functions and what methods they support go to the API Documentation.

RESTful APIs often use the GET, POST, PUT and DELETE methods of the HTTP protocol. We think this would make our API overcomplicated. Our API started out very small and simple and have gradually grown. Because of this we choose to only use the POST method and a clear module/function structure. We have also added support for the GET method to some functions. If a function supports both POST and GET, it doesn't matter what method you use, they are functionally identical.

The reason for adding support for GET is that it is so simple to use. You could just use a web browser (or script) to visit https://CL12345:API-KEY@api.glesys.com/server/list to list your servers. If you use a web browser you can even leave out the username and password, visit https://api.glesys.com/server/list and let the browser ask you for the information.

Construction of API calls

URL

The URL of an API call is constructed in the following manner.

https://api.glesys.com/module/function/

You will always need to supply the name of the module and the name of the function that you want to call. If you request the URL https://api.glesys.com/server/list you make a call to the list function of the server module. This function will list all servers on your account.

If you make a request directly to https://api.glesys.com/ without supplying a module or a function, you will get a list of all available modules. If you make a request to an existing module but leave out the name of the function, you will get a list of all functions that are available in this module (ex: https://api.glesys.se/server ). The same information is also available on the API Documentation page.

Arguments

Many of the functions also take arguments. Some of the arguments are required and some of them are optional. For a full list of arguments for each function, and which are required or optional, take a look at the API Documentation page

If you use the POST method the arguments should be provided in the body of the request. It could look like this:

serverid=vz123&type=reboot

Together with the url https://api.glesys.com/server/stop, this call will reboot the server with serverid vz123.

If you use GET, all arguments is listed in the url in the following format:

argumentname1/value1/argumentname2/value2

The complete URL for listing free IPv6 addresses in Falkenberg for the OpenVZ platform would then become:

https://api.glesys.com/ip/listfree/platform/OpenVZ/datacenter/Falkenberg/ipversion/6

If a function is called and the arguments doesn't pass validation, an error describing what went wrong is displayed. Be sure to escape any arguments passed to the API. For instance, replace spaces with + signs. A call to the function server/create with the following arguments;

disksize=five&template=Windows+3.11&platform=VMware

will result in the following output.

<?xml version=\"1.0\" encoding=\"utf-8\"?>
<xml>
 <response>
  <status>
   <code>400</code>
   <text>The datacenter field is required.
    The hostname field is required.
    The template is not a template. Allowed: Ubuntu 11.04 x64, CentOS 5.5 x64, CentOS 5.5 x86, Debian 5.0.1 x64, Gentoo 10.1 x64, Ubuntu 10.10 x64, Ubuntu 8.04 x64, Windows Server 2008 x86 web, Windows Server 2008 x64 web, Debian-6 x64, Ubuntu 10.04 LTS 64-bit, Windows Server 2008 R2 x64 web
    The disksize is not a valid disksize. Allowed: 5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 120, 140, 150, 200, 250, 300
    The memorysize field is required.
    The cpucores field is required.
    The rootpw field is required.
    The transfer field is required.
   </text>
   <transactionid/>
  </status>
  <arguments>
   <disksize>five</disksize>
   <template>Windows 3.11</template>
   <platform>Xen</platform>
  </arguments>
 </response>
</xml>

This makes the API somewhat self documenting.

Formats

You can choose both the input and output format of the request and output format.

Input

You set the format of the data sent to the API by setting Content-Type: application/json or Content-Type: application/x-www-form-urlencoded in your request. application/json is the recommended format.

Please note that the request body needs to be a valid JSON object when using application/json and properly URL encoded data when using application/x-www-form-urlencoded.

Full example using application/json:

> POST /server/details HTTP/1.1
> Host: api.glesys.com
> Authorization: Basic ...
> Accept: application/json
> Content-Type: application/json
> Content-Length: 28

| {
| 	"serverid": "vz1234567"
| }

Full example using application/x-www-form-urlencoded:

> POST /server/details HTTP/1.1
> Host: api.glesys.com
> Authorization: Basic ...
> Accept: application/json
> Content-Type: application/x-www-form-urlencoded
> Content-Length: 18

| serverid=vz1234567

Output

You can also change the format of the output from the API. You do this by setting Accept: application/json or Accept: application/xml.

Due to legacy reasons application/xml will be used if the Accept header is omitted from the request.

We recommend setting Accept: application/json in all of your requests.

Testing

cURL

To use cURL it is probably the easiest way to test our API. Just visit the API Documentation page and copy the curl examples that are available for each of the functions. Just change the username, API key, set the parameters to real values and run the command.

Wiztools RESTClient

Another great way to test our API is to download the Wiztools RESTClient. It is based on Java and should be able to run on most platforms. It can be found here: http://code.google.com/p/rest-client/

For starters, download and run the application.

As the URL, type in https://api.glesys.com followed by the module and the function. To list servers, you should type in https://api.glesys.com/server/list.

In the Method tab, set the HTTP Method to GET or POST. You can take a look at the documentation to see which functions support which method. It is safe to select POST here as all functions support POST.

If you use POST, you have to set the Content-Type. Click on the button with the pencil and window in the Body tab. Select application/x-www-form-urlencoded as the content-type. Leave the charset as UTF-8.

The arguments can now be listed in the text-field in the body tab in the following format:

platform=OpenVZ&datacenter=Falkenberg&ipversion=6

The URL should be set to reference the module and function. In this case: https://api.glesys.com/server/details.

If you use GET, all arguments are listed in the URL in the following format:

platform/OpenVZ/datacenter/Falkenberg/ipversion/6

The complete url in this case will then become:

https://api.glesys.com/ip/listfree/platform/OpenVZ/datacenter/Falkenberg/ipversion/6

Last, but not least, you need to supply your username and password (API key) in the Auth tab.

Execute the API call by clicking the button with arrows next to the URL field.

Tip: Save your request by going to File->Save Request in the menu. This way you can just open the saved request the next time you start the application and won’t have to fill our username, API key, Content-Type etc.

Clone this wiki locally