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

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

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

HTTP-Response Headers

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:

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.

GET

• Collection Endpunkt: https://api.gridscale.io/objects/servers
• Objekt Endpunkt: https://api.gridscale.io/objects/servers/

API-Response

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

Response:

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"}