Getting Started mit der gridscale API

Im Durchschnitt wird dieses Tutorial Getting Started mit der gridscale API mit 5 bewertet, wobei 1.0 die schlechteste und 5.0 die beste Bewertung ist. Es haben insgesamt 678 Besucher eine Bewertung abgegeben.
678 0

Getting Started mit der gridscale API

API gridscale
tutorial - getting started mit der gridscale API

gridscale API

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.

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-MethodeBeschreibung
GETEine simple Abfrage von Informationen. Die Antwort erfolgt als JSON Objekt. Requests mit GET sind immer Read-Only.
POSTErstellt 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.
DELETELö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.
OPTIONSLiefert 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-StatusNachrichtBeschreibung
200OKDie Anfrage wurde erfolgreich bearbeitet und das Ergebnis der Anfrage wird in der Antwort übertragen.
202AcceptedDie Anfrage wurde akzeptiert, wird aber zu einem späteren Zeitpunkt ausgeführt. Das Gelingen der Anfrage kann nicht garantiert werden.
204No ContentDie Anfrage wurde erfolgreich durchgeführt, die Antwort enthält jedoch bewusst keine Daten.
400Bad RequestDie Anfrage-Nachricht war fehlerhaft aufgebaut.
401UnauthorizedDie 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.
402Payment RequiredAktion kann nicht ausgeführt werden – keine oder ungültige Zahlungsmethoden hinterlegt.
403ForbiddenDie Anfrage wurde nicht durchgeführt mangels Berechtigung des Users oder weil eine unmögliche Aktion angefragt wurde.
404Not FoundDie angeforderte Ressource wurde nicht gefunden. Wird ebenfalls verwendet, wenn eine Ressource zwar existiert, aber der User keine Berechtigung dafür besitzt.
405Method Not AllowedDie Anfrage darf nur mit anderen HTTP-Methoden (zum Beispiel GET statt POST) gestellt werden.
409ConflictDie Anfrage wurde unter falschen Annahmen gestellt. Zum Beispiel kann ein User mit der gleichen E-Mail nicht zweimal erstellt werden.
415Unsupported Media TypeDer 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.
424Failed DependencyDie 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

HeaderBeschreibung
Content-TypeAktuell immer „application/json“.
X-Auth-UserIdDie 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-TokenIst 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

HeaderBeschreibung
Content-TypeAktuell immer „application/json“.
X-Exec-TimeDie Zeit, die das Provisioning intern benötigt hat um die Anfrage zu bearbeiten (in ms)
X-Api-VersionDie 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:

HeaderParameterBeschreibung
Access-Control-Allow-MethodsGET, POST, PUT, PATCH, DELETE, OPTIONSEnthält alle verfügbaren Methoden die für Anfragen verwendet werden dürfen.
Access-Control-Allow-CredentialstrueIst auf „true“ gesetzt. Erlaubt dem Browser die Authentifizierungsdaten via X-Auth HTTP-Header zu senden.
Access-Control-Allow-HeadersOrigin, X-Requested-With, Content-Type, Accept, X-Auth-UserId, X-Auth-Token , X-Exec-Time, X-Api-VersionDie für Anfragen verfügbaren HTTP-Header.
Access-Control-Allow-Origin*Die vom Browser gesendete Domain als Quelle der Anfrage.
Access-Control-Expose-HeadersX-Exec-Time, X-Api-VersionDie 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.

EndpunktBeschreibung
/The API root
/pricesOverview of current resource prices
/objects/locationsList of locations
/objects/locations//serversList servers available in location
/objects/locations//storagesList storages available in location
/objects/locations//networksList networks available in location
/objects/locations//ipsList ips available in location
/objects/locations//templatesList of templates available in location
/objects/storagesActions for storages
/objects/storages//eventsEvents for a storage
/objects/storages//snapshotsActions for snapshots of a storage
/objects/storages//rollbackActions for snapshot rollback of a storage
/objects/networksActions for networks
/objects/networks//eventsEvents for a network
/objects/serversActions for servers
/objects/servers//eventsEvents for a server
/objects/servers//powerPower-Actions for server
/objects/servers//storagesActions for server-storage relations
/objects/servers//networksActions for server-network relations
/objects/servers//ipsActions for server-ip relations
/objects/servers//isoimagesActions for server-isoimage relations
/objects/servers//distanceActions for near/far distance relations
/objects/isoimagesActions for isoimages
/objects/isoimages//eventsEvents for an isoimage
/objects/ipsActions for ips
/objects/ips//eventsEvents for an ip
/objects/templatesActions for templates
/objects/templates//eventsEvents for a template
/objects/sshkeysActions for SSH keys
/objects/sshkeys//eventsEvents for a sshkey
/objects/deleted/serversActions for deleted servers
/objects/deleted/storagesActions for deleted storages
/objects/deleted/networksActions for deleted networks
/objects/deleted/snapshotsActions for deleted snapshots
/objects/deleted/templatesActions for deleted templates
/objects/deleted/isoimagesActions for deleted isoimages
/objects/deleted/ipsActions 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

AttributDatentypBeschreibung
object_uuidstringserver uuid
namestringname of the server
labelsobjectlist of labels – each label is a string
coresintegernumber of cores
memoryintegeramount of memory in GiB
statusstringcurrent status of the server
powerbooleanpower status of the server (on: true, off: false)
create_timedatetimeISO 8601 combined date and time in UTC
change_timedatetimeISO 8601 combined date and time in UTC
location_uuidstringlocation uuid
location_namestringname of the location
location_countrystringISO 3166-2 country code
location_iatastringIATA airport code – location identifier
console_tokenstringconsole token for this servers local console (via websocket)
current_pricefloatcurrent object price for the current period since the last billing time
relationsobjectlist 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

ParameterDatentypOptional
namestring
labelslistja
coresinteger
memoryinteger
location_uuidstring

Response:

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

gridscale API 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. Das Getting Started wird dir einen […]

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 Getting started mit dem gridscale Load Balancer?

×

Entwickler?

Dann einfach hier für unsere Tutorial-Updates anmelden.
Keine Sorge: Wir spammen dich nicht zu