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:
Request Methods
HTTP-Method | Description |
---|---|
GET | A simple query of information. The answer is given as a JSON object. Requests with GET are always read-only. |
POST | Creates new objects and object relations. The POST request must contain all necessary parameters in a JSON object. |
PATCH | Changes an object or an object relation. The parameters in PATCH requests are usually optional, so that only the changed parameters must be specified in a JSON object. |
DELETE | Deletes an object or object relation. The object is deleted if it exists. If it does not exist or has already been successfully deleted, a “404 Not Found” is sent. |
OPTIONS | Returns a list of methods and characteristics supported by the server. |
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
HTTP status | Message | Description |
---|---|---|
200 | OK | The request has been processed successfully and the result of the request is given in the response. |
202 | Accepted | The request has been accepted, but will be executed at a later time. The success of the request cannot be guaranteed. |
204 | No Content | The request was successful, but the response deliberately does not contain any data. |
400 | Bad Request | The request message had an incorrect structure./td> |
401 | Unauthorized | The request cannot be executed without valid authentication. X-Auth-UserId or X-Auth-Token HTTP-Header not set or UserID/Token invalid. |
402 | Payment Required | Action cannot be executed – no or invalid payment methods stored. |
403 | Forbidden | The request was not executed because the user is not authorized or because an impossible action was requested. |
404 | Not Found | The requested resource was not found. Also used if a resource exists but the user has no authorization for it. |
405 | Method Not Allowed | The request may only be made using other HTTP methods (for example, GET instead of POST). |
409 | Conflict | The request was made under false assumptions. For example, a user cannot be created twice with the same e-mail. |
415 | Unsupported Media Type | The content of the request was submitted with invalid or invalid media type. All requests with POST or PATCH must use “Content-Type: application/json” and a JSON object as payload. |
424 | Failed Dependency | The query could not be executed because the object is in the wrong status. |
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
Header | Description |
---|---|
Content type | “application/json”. |
X-Auth-UserId | The user UUID. This can be read out in the panel under “API” and remains the same for a user as long as it exists (e.g. even after changing the user e-mail). |
X-Auth-Token | Is a hash generated by the API and must be sent with all API requests. Both the token and its permissions can be configured in the panel. |
HTTP-Response Headers
Header | Description |
---|---|
Content type | “application/json”. |
X-Exec-Time | The time that provisioning took internally to process the request (in ms) |
X-Api-Version | The currently active Provisioning API version. Useful when reporting bugs to us |
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:
Header | Parameter | Description |
---|---|---|
Access-Control-Allow-Methods | GET, POST, PUT, PATCH, DELETE, OPTIONS | Contains all available methods that may be used for queries. |
Access-Control-Allow-Credentials | true | Is set to true. Allows the browser to send authentication data via X-Auth HTTP headers. |
Access-Control-Allow-Headers | Origin, X-Requested-With, Content-Type, Accept, X-Auth-UserId, X-Auth-Token , X-Exec-Time, X-Api-Version | The HTTP headers available for requests. |
Access-Control-Allow-Origin | * | The domain sent by the browser as the source of the request. |
Access-Control-Expose-Headers | X-Exec-Time, X-Api-Version | The HTTP headers that can be used by a browser application. |
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.
Endpoint | Description |
---|---|
/ | The API root |
/prices | Overview of current resource prices |
/objects/locations | List of locations |
/objects/locations//servers | List servers available in location |
/objects/locations//storages | List storages available in location |
/objects/locations//networks | List networks available in location |
/objects/locations//ips | List ips available in location |
/objects/locations//templates | List of templates available in location |
/objects/storages | Actions for storages |
/objects/storages//events | Events for a storage |
/objects/storages//snapshots | Actions for snapshots of a storage |
/objects/storages//rollback | Actions for snapshot rollback of a storage |
/objects/networks | Actions for networks |
/objects/networks//events | Events for a network |
/objects/servers | Actions for servers |
/objects/servers//events | Events for a server |
/objects/servers//power | Power-Actions for server |
/objects/servers//storages | Actions for server-storage relations |
/objects/servers//networks | Actions for server-network relations |
/objects/servers//ips | Actions for server-ip relations |
/objects/servers//isoimages | Actions for server-isoimage relations |
/objects/servers//distance | Actions for near/far distance relations |
/objects/isoimages | Actions for isoimages |
/objects/isoimages//events | Events for an isoimage |
/objects/ips | Actions for ips |
/objects/ips//events | Events for an ip |
/objects/templates | Actions for templates |
/objects/templates//events | Events for a template |
/objects/sshkeys | Actions for SSH keys |
/objects/sshkeys//events | Events for a sshkey |
/objects/deleted/servers | Actions for deleted servers |
/objects/deleted/storages | Actions for deleted storages |
/objects/deleted/networks | Actions for deleted networks |
/objects/deleted/snapshots | Actions for deleted snapshots |
/objects/deleted/templates | Actions for deleted templates |
/objects/deleted/isoimages | Actions for deleted isoimages |
/objects/deleted/ips | Actions for deleted ips |
/objects/locations/ | Infos about a location |
/objects/storages/ | Actions for a storage |
/objects/storages//snapshots/ | Actions for a snapshot |
/objects/networks/ | Actions for a network |
/objects/servers/ | Actions for a server |
/objects/servers//storages/ | Actions for a server-storage relation |
/objects/servers//networks/ | Actions for a server-network relation |
/objects/servers//ips/ | Actions for a server-ip relation |
/objects/servers//distance/ | Actions for a near/far distance relation |
/objects/ips/ | Actions for an ip |
/objects/templates/ | Actions for a template |
/objects/sshkeys/ | Actions for a SSH key |
GET
- Endpoint collection: https://api.gridscale.io/objects/servers
- Endpoint object: https://api.gridscale.io/objects/servers/
API-Response
Attribut | Datatyp | Description |
---|---|---|
object_uuid | string | server uuid |
name | string | name of the server |
labels | object | list of labels – each label is a string |
cores | integer | number of cores |
memory | integer | amount of memory in GiB |
status | string | current status of the server |
power | boolean | power status of the server (on: true, off: false) |
create_time | datetime | ISO 8601 combined date and time in UTC |
change_time | datetime | ISO 8601 combined date and time in UTC |
location_uuid | string | location uuid |
location_name | string | name of the location |
location_country | string | ISO 3166-2 country code |
location_iata | string | IATA airport code – location identifier |
console_token | string | console token for this servers local console (via websocket) |
current_price | float | current object price for the current period since the last billing time |
relations | object | list of relations to and from this server (siehe: “relations” unter dieser Tabelle) |
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
Parameter | Data type | Optional |
---|---|---|
name | string | |
labels | list | ja |
cores | integer | |
memory | integer | |
location_uuid | string |
Response:
Attribut | Data type | Description |
---|---|---|
object_uuid | string | UUID of the new Server |
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"}Zurück zur Tutorial Übersicht Back to Tutorial Overview
Thank you for your feedback!
We will get back to you as soon as the article is finished.
Übrigens: kennst du schon unser Tutorial zum Thema The gridscale 1-Click WordPress Template?