Getting Started mit der gridscale API

gridscale API

=======
Willkommen zur gridscale API Dokumentation.

Mit der gridscale API kannst alle deine Server und Ressourcen in der gridscale Cloud über eine mächtige und trotzdem einfach zu nutzen 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.

Die Dokumentation wird dir einen Überblick über die grundlegenden Funktionen, das Design der API und allen API-Endpunkten geben.

Noch nicht bei gridscale registriert?

 

 

Sichere dir jetzt € 10 Startguthaben.

Jetzt registrieren

Danke, bitte schau in den Postfach

Für unsere Tutorial-Updates anmeldenKeine Sorge: Wir spammen dich nicht zu

Tutorials erhalten

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:

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 Standorte 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.

/objects/servers

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