Getting Started mit der gridscale API

gridscale API
Mit der gridscale API kannst du alle deine Server und Ressourcen in der gridscale Cloud über eine mächtige und trotzdem einfach zu nutzende RESTful API verwalten. Zur Verfügung stehen alle Funktionen aus der Web-Panel GUI und darüber hinaus noch viele Expertenfunktionen wie z.B. Storage verkleinern oder Hotplug Mechanismen.
Das Getting Started wird dir einen Überblick über die grundlegenden Funktionen, das Design der API und allen API-Endpunkten geben.
Die vollständige gridscale API Dokumentation up to date findest du hier:
gridscale API Documentation
Request Methoden
HTTP-Methode | Beschreibung |
---|---|
GET | Eine simple Abfrage von Informationen. Die Antwort erfolgt als JSON Objekt. Requests mit GET sind immer Read-Only. |
POST | Erstellt neue Objekte und Objekt-Relationen. Der POST Request muss alle notwendigen Parameter in einem JSON Objekt enthalten. |
PATCH | Ändert ein Objekt oder eine Objekt-Relation. Die Parameter in PATCH Requests sind in der Regel optional, so dass nur die geänderten Parameter in einem JSON Objekt angegeben werden müssen. |
DELETE | Löscht ein Objekt oder Objekt-Relation. Das Objekt wird gelöscht, wenn es existiert. Wenn es nicht existiert oder bereits erfolgreich gelöscht wurde, wird mit einem „404 Not Found“ geantwortet. |
OPTIONS | Liefert eine Liste der vom Server unterstützen Methoden und Merkmale. |
Die Methoden PATCH und DELETE sind indempotent – das heißt: wird ein Request mit identischen Parametern mehrfach gesendet, ändert sich nichts am Ergebnis.
HTTP-Statuscodes
HTTP-Status | Nachricht | Beschreibung |
---|---|---|
200 | OK | Die Anfrage wurde erfolgreich bearbeitet und das Ergebnis der Anfrage wird in der Antwort übertragen. |
202 | Accepted | Die Anfrage wurde akzeptiert, wird aber zu einem späteren Zeitpunkt ausgeführt. Das Gelingen der Anfrage kann nicht garantiert werden. |
204 | No Content | Die Anfrage wurde erfolgreich durchgeführt, die Antwort enthält jedoch bewusst keine Daten. |
400 | Bad Request | Die Anfrage-Nachricht war fehlerhaft aufgebaut. |
401 | Unauthorized | Die Anfrage kann nicht ohne gültige Authentifizierung durchgeführt werden. X-Auth-UserId oder X-Auth-Token HTTP-Header nicht gesetzt oder UserID/Token invalid. |
402 | Payment Required | Aktion kann nicht ausgeführt werden – keine oder ungültige Zahlungsmethoden hinterlegt. |
403 | Forbidden | Die Anfrage wurde nicht durchgeführt mangels Berechtigung des Users oder weil eine unmögliche Aktion angefragt wurde. |
404 | Not Found | Die angeforderte Ressource wurde nicht gefunden. Wird ebenfalls verwendet, wenn eine Ressource zwar existiert, aber der User keine Berechtigung dafür besitzt. |
405 | Method Not Allowed | Die Anfrage darf nur mit anderen HTTP-Methoden (zum Beispiel GET statt POST) gestellt werden. |
409 | Conflict | Die Anfrage wurde unter falschen Annahmen gestellt. Zum Beispiel kann ein User mit der gleichen E-Mail nicht zweimal erstellt werden. |
415 | Unsupported Media Type | Der Inhalt der Anfrage wurde mit ungültigem oder nicht erlaubtem Medientyp übermittelt. Alle Anfragen mit POST oder PATCH müssen „Content-Type: application/json“ und ein JSON-Objekt als Payload nutzen. |
424 | Failed Dependency | Die Anfrage konnte nicht durchgeführt werden, weil das Objekt im falschen Status ist. |
Status 200-204 besagen, dass die Anfrage akzeptiert wurde und bearbeitet wird (202) oder wurde (200, 204).
Status 400-424 besagen, dass es ein Problem mit der Anfrage gab. Nähere Information zum Problem findest du im Body der 4xx Antwort.
Ein Status 500 bedeutet, dass es ein Server-seitiges Problem gab und deine Anfrage gerade nicht bearbeitet werden kann.
HTTP-Request Headers
Header | Beschreibung |
---|---|
Content-Type | Aktuell immer „application/json“. |
X-Auth-UserId | Die User-UUID. Diese kann im Panel unter „API“ ausgelesen werden und bleibt für einen User solange er existiert gleich (z.B. auch nach der Änderung der User E-Mail). |
X-Auth-Token | Ist ein von der API generierter Hash der bei allen API-Anfragen mitgesendet werden muss. Sowohl der Token als auch dessen Berechtigungen können im Panel konfiguriert werden. |
HTTP-Response Headers
Header | Beschreibung |
---|---|
Content-Type | Aktuell immer „application/json“. |
X-Exec-Time | Die Zeit, die das Provisioning intern benötigt hat um die Anfrage zu bearbeiten (in ms) |
X-Api-Version | Die aktuell aktive Provisioning API Version. Nützlich bei der Meldung von Bugs an uns |
Timestamp-Format
Alle Timestamps folgen ISO-8601 und werden in UTC ausgegeben.
CORS – Cross Origin Resource Sharing
Um API-Zugriffe aus anderen Domains zu erlauben, unterstützt die API CORS (Cross Origin Resource Sharing). Siehe hierzu: enable-cors.org/.
Dies erlaubt im Browser laufenden JavaScript Web Control Panels direkt die API zu nutzen.
Das alles erfolgt im Hintergrund durch den Browser. Folgende HTTP-Header werden von der API gesetzt:
Header | Parameter | Beschreibung |
---|---|---|
Access-Control-Allow-Methods | GET, POST, PUT, PATCH, DELETE, OPTIONS | Enthält alle verfügbaren Methoden die für Anfragen verwendet werden dürfen. |
Access-Control-Allow-Credentials | true | Ist auf „true“ gesetzt. Erlaubt dem Browser die Authentifizierungsdaten via X-Auth HTTP-Header zu senden. |
Access-Control-Allow-Headers | Origin, X-Requested-With, Content-Type, Accept, X-Auth-UserId, X-Auth-Token , X-Exec-Time, X-Api-Version | Die für Anfragen verfügbaren HTTP-Header. |
Access-Control-Allow-Origin | * | Die vom Browser gesendete Domain als Quelle der Anfrage. |
Access-Control-Expose-Headers | X-Exec-Time, X-Api-Version | Die HTTP-Header, die von einer Browser Applikation verwendet werden dürfen. |
API Endpunkte
Für Beispiele der API-Anfragen nutzen wir cURL. Es kann auf den meisten Betriebssystemen verwendet werden und ermöglicht eine einfache, übersichtliche Darstellung von Anfragen im Textformat.
Um die Beispiele möglichst einfach und direkt testen zu können, nutzen wir Variablen als Platzhalter die du als Environment-Variable definieren kannst. Somit kannst du die Beispiele per Copy&Paste direkt selbst ausprobieren:
# in deinem aktiven Linux-Terminal oder putty-Fenster export X_USERID=deine_user_uuid export X_TOKEN=dein_token
Generiere dir dein erstes API-Token.
Beispiele
Alle Parameter in POST oder PATCH Anfragen müssen in einem JSON Objekt als key-value Paare übergeben werden.
Verfügbare Standort abfragen
Mit dem folgenden Befehl, kannst du alle für dich verfügbaren Serverstandorte auslesen.
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" } } }
Server erstellen
Zum Erstellen eines neuen Servers wird der Standort (location_uuid) benötigt, in dem der Server eingerichtet werden soll. Der Standort kann später nicht mehr geändert werden.
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"}
Die Response enthält die „object_uuid“ des erstellten Servers und kann in weiteren Requests genutzt werden, zum Beispiel um Informationen zu dem gerade angelegten Server per GET abzufragen.
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
API OPTIONS abfragen
Unsere API ist selbst-beschreibend – für jeden Endpunkt kannst du mit der HTTP OPTIONS-Methode eine Übersicht der möglichen Aktionen, Parameter sowie Request und Response Werte erhalten. Du kannst diese Informationen zum Beispiel in deinen Automations-Tools nutzen.
Abfragen mit OPTIONS benötigen keine Authentifizierung.
curl -X OPTIONS \ -i \ https://api.gridscale.io/objects/servers
OPTIONS
- Collection Endpunkt: https://api.gridscale.io
Gibt eine Liste aller verfügbaren API Endpunkte aus.
Endpunkt | Beschreibung |
---|---|
/ | 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
- Collection Endpunkt: https://api.gridscale.io/objects/servers
- Objekt Endpunkt: https://api.gridscale.io/objects/servers/
API-Response
Attribut | Datentyp | Beschreibung |
---|---|---|
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
Die Relationen im Server Objekt dienen deinem Komfort – wir haben bereits alle Informationen so für dich zusammengefasst, dass du eine kompletten Überblick über deinen Server hast. Alle Relationen können auch über ihre eigenen API-Endpunkte abgefragt werden und enthalten sowohl hier als auch dort jeweils identische Daten.
Folgende Relationen werden im Server Objekt beschrieben:
- distance
- isoimages
- storages
- public_ips
- networks
POST
Einen neuen Server erstellen.
Request
Parameter | Datentyp | Optional |
---|---|---|
name | string | |
labels | list | ja |
cores | integer | |
memory | integer | |
location_uuid | string |
Response:
Attribut | Datentyp | Beschreibung |
---|---|---|
object_uuid | string | UUID des neuen Servers |
Beispiel
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