0 0 0

Getting Started mit der gridscale API

vom gridscale Team API gridscale

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.

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: http://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.

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

/objects/servers

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

Schade, dass dir der Artikel nicht gefallen hat.
Was sollten wir deiner Meinung nach besser machen?

Vielen Dank für dein Feedback!
Wir melden uns bei dir, sobald der Artikel zu deinem Wunschthema fertig ist.

Übrigens: kennst du schon unser Tutorial zum Thema Zwei Server mit internem Netz via RESTful API installieren?