Getting started gridscale API

gridscale API

With the gridscale API you can manage all your servers and resources in the gridscale cloud with a powerful yet easy to use RESTful API. All functions from the Web-Panel GUI and many other expert functions are available, e.g. scaling down storage or hotplug mechanisms.

Here we will give you an overview of the basic functions, API design and all API endpoints.

The complete gridscale API documentation can be found here:

gridscale API Documentation

Request Methods

The methods PATCH and DELETE are duplicated – that is, if a request with identical parameters is sent more than once, nothing changes in the result.

HTTP status codes

Status 200-204 indicates that the request has been accepted and is being processed (202) or has been (200, 204).

Status 400-424 indicate that there was a problem with the request. You can find more information about the problem in the body of the 4xx answer.

A status 500 means that there was a server-side problem and your request cannot be processed.

HTTP-Request Headers

HTTP-Response Headers

Timestamp format

All timestamps follow ISO-8601 and are output in UTC.

CORS – Cross Origin Resource Sharing

To allow API access from other domains, the API supports CORS (Cross Origin Resource Sharing). See also: enable-cors.org/.

This allows JavaScript Web Control Panels running in the browser to use the API directly.

All this is done in the background by the browser. The following HTTP headers are set by the API:

API Endpoints

For examples of API requests we use cURL. It can be used on most operating systems and enables a simple, clear display of queries in text format.

To test the examples as easily and directly as possible, we use variables as placeholders which you can define as environment variables. So you can try out the examples directly yourself using Copy&Paste:

# in your active Linux terminal or putty window
export X_USERID=your_user_uuid
export X_TOKEN=your_token

Generate your API-Token.

Examples

All parameters in POST or PATCH requests must be passed in a JSON object as key-value pairs.

Query available location

With the following command, you can get all server locations available for you.

curl -H "Content-Type: application/json" \
     -H "X-Auth-UserId: $X_USERID" \
     -H "X-Auth-Token: $X_TOKEN" \
     -X GET \
     -i \
     https://api.gridscale.io/objects/locations

API-Response

{ 
  "locations": { 
    "39a7d783-3873-4b2f-915b-4c86c28344e5": { 
      "object_uuid": "39a7d783-3873-4b2f-915b-4c86c28344e5", 
      "name": "de/fra", 
      "country": "de", 
      "iata": "fra" 
    } 
  } 
}

Create Server

To create a new server, the location (location_uuid) is required in which the server is to be set up. The location cannot be changed later.

curl -H "Content-Type: application/json" \
     -H "X-Auth-UserId: $X_USERID" \
     -H "X-Auth-Token: $X_TOKEN" \
     -X POST \
     -d '{"name": "ServerName", "cores":1, "memory":4, "location_uuid":"39a7d783-3873-4b2f-915b-4c86c28344e5"}' \
     -i \
     https://api.gridscale.io/objects/servers

API Response

{"object_uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"}

The response contains the “object_uuid” of the created server and can be used in further requests, for example to request information about the server that has just been created via GET.

curl -H "Content-Type: application/json" \
     -H "X-Auth-UserId: $X_USERID" \
     -H "X-Auth-Token: $X_TOKEN" \
     -X GET \
     -i \
     https://api.gridscale.io/objects/servers/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Query API OPTIONS

Our API is self-descriptive – for each endpoint you can use the HTTP OPTIONS method to get an overview of the possible actions, parameters, request and response values. You can use this information in your automation tools, for example.

Queries with OPTIONS do not require authentication.

curl -X OPTIONS \
     -i \
     https://api.gridscale.io/objects/servers

OPTIONS

• Endpoint collection: https://api.gridscale.io

Returns a list of all available API endpoints.

GET

• Endpoint collection: https://api.gridscale.io/objects/servers
• Endpoint object: https://api.gridscale.io/objects/servers/

API-Response

relations

The relations in the server object serve your comfort – we have already summarized all information for you in such a way that you have a complete overview of your server. All relations can also be queried via their own API endpoints and contain identical data both here and there.

The following relations are described in the server object:

• distance
• isoimages
• storages
• public_ips
• networks

POST

Create a new server.

Request

Response:

Example

Request:

curl -H "Content-Type: application/json" \
     -H "X-Auth-UserId: $X_USERID" \
     -H "X-Auth-Token: $X_TOKEN" \
     -X POST \
     -d '{"name": "ServerName", "cores":1, "memory":4, "location_uuid":"39a7d783-3873-4b2f-915b-4c86c28344e5"}' \
     -i \
     https://api.gridscale.io/objects/servers

Response

{"object_uuid": "738aa5e3-b1f5-43df-a77b-085c1a6367f7"}