API verwenden

Last change on 2022-11-21 • Created on 2022-11-21 • ID: CL-09EB0

  1. Nutze deinen API-Token

    Um die API nutzen zu können, benötigst du einen API-Token. Achte darauf, dass du für jedes Projekt einen eigenen API-Token erstellen musst, da jeder API-Token an das Projekt gebunden ist, in dem er erstellt wurde und für kein zweites Projekt genutzt werden kann.

    Wenn du noch keinen API-Token besitzt, erstelle ihn jetzt. Im Getting Started "API-Token hinzufügen" wird Schritt für Schritt erklärt, wie das geht. Denk daran, den API-Token nach dem Erstellen zu kopieren und zu speichern, da es nicht möglich ist, sich diesen erneut anzeigen zu lassen.

    In allen Beispiel-Befehlen wird $API_TOKEN als Platzhalter angegeben. Beachte, dass $API_TOKEN mit deinem tatsächlichen API-Token ersetzt werden muss. Beispiel:

    -H "Authorization: Bearer $API_TOKEN" \
    -H "Authorization: Bearer jEheVytlAoFl7F8MqUQ7jAo2hOXASztX" \
    Beispiel-Projekt
    Projekt 1
    $API_TOKEN_1
    2x
    Server
    2x
    Primary IP
    1x
    Privates Netzwerk
    Projekt 2
    $API_TOKEN_2
    1x
    Server
    1x
    Primary IP
    1x
    Firewall


    Um über die zwei Server in "Projekt 1" Informationen anzufragen, musst du im Curl-Befehl $API_TOKEN_1 angeben:

    curl \
       -H "Authorization: Bearer $API_TOKEN_1" \
       'https://api.hetzner.cloud/v1/servers'

  1. Nutze die Dokumentation

    Öffne die Cloud API Dokumentation und nutze die linke Menüleiste, um zu den Punkten zu navigieren, die für dich relevant sind.

    cloud-api-docs 

    Je nachdem, was du anfragst, musst du einen von vier Requests ausführen.
    Die vier Requests im Überblick
    GET
    Read
    curl \
      -H "Authorization: Bearer $API_TOKEN" \
      'https://api.hetzner.cloud/v1/{api-url-ending}'
    Information über verfügbare Tarife, Ressourcen, Standorte oder anderes anfragen.

    POST
    Read & Write
    curl \
      -X POST \
      -H "Authorization: Bearer $API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"eigenschaft":wert,"eigenschaft":wert,...}' \
      'https://api.hetzner.cloud/v1/{api-url-ending}'
    Neue Ressourcen erstellen und/oder konfigurieren

    PUT
    Read & Write
    curl \
      -X PUT \
      -H "Authorization: Bearer $API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"eigenschaft":wert,"eigenschaft":wert,...}' \
      'https://api.hetzner.cloud/v1/{api-url-ending}/{id}'
    Die Eigenschaften bestehender Ressourcen bearbeiten

    DELETE
    Read & Write
    curl \
      -X DELETE \
      -H "Authorization: Bearer $API_TOKEN" \
      'https://api.hetzner.cloud/v1/{api-url-ending}/{id}'
    Bestehende Ressourcen löschen

  1. Curl-Befehl kopieren

    Sobald du zu einem der Punkte navigiert hast, überprüfst du, welche Art von Request erforderlich ist, und kopierst die API-Endung:

    api-request

    In diesem Beispiel ist die Request-Art GET und die API-Endung /servers.

    Mit dieser Information erfährst du, welchen Curl-Befehl du ausführen musst. Am rechten Rand der API-Dokumentation gibt es zusätzlich noch einen Beispiel-Befehl. Über das Aufklappmenü kannst du die Anzeige zu curl wechseln. In diesem Beispiel (GET /servers), wäre der entsprechende Curl-Befehl:

    api-request 

    curl \
    -H "Authorization: Bearer $API_TOKEN" \
    'https://api.hetzner.cloud/v1/servers'

    Beachte, dass $API_TOKEN mit dem eigenen API-Token ersetzt werden muss.

    Der Curl-Befehl erklärt
    • -X {request-type} Mit der ersten Zeile wird normalerweise bestimmt, welche Art von Request es ist. Bei GET Requests wird diese Zeile aber nicht benötigt.
    • -H "Authorization: Bearer $API_TOKEN" In dieser Zeile wird der API-Token angegeben. Da der API-Token an ein bestimmtes Projekt gebunden ist, wird hiermit bestimmt in welchem Projekt der Request ausgeführt werden soll.
    • Bei POST und PUT Requests müssen manchmal bestimmte Eigenschaften definiert werden, die zum Erstellen oder Bearbeiten einer Ressource erforderlich sind. Eine solche Eigenschaft könnte beispielsweise ein Name ("name":"unique-name") oder der Typ ("type":"ipv4") sein. Um diese Informationen anzugeben, sind zwei zusätzliche Zeilen erforderlich:
      curl \
         -X POST \
         -H "Authorization: Bearer $API_TOKEN" \
      +  -H "Content-Type: application/json" \
      +  -d '{"eigenschaft":wert,"eigenschaft":wert,...}' \
         'https://api.hetzner.cloud/v1/servers'

  1. Eigenschaften zu einem POST oder PUT Request hinzufügen

    Wenn du eine neue Ressource erstellen oder eine bestehende bearbeiten möchtest, wirst du vermutlich Eigenschaften wie einen Namen oder einen Standort angeben müssen.

    Um schnell loszulegen, kannst du schlicht den Beispiel-Befehl am rechten Rand kopieren. Der Beispiel-Befehl enthält alle wesentlichen Eigenschaften und du musst lediglich die Werte anpassen und Eigenschaften, die du nicht bestimmen möchtest, entfernen. Beachte dabei aber, dass manche Eigenschaften nicht optional sind und angegeben werden müssen. Um mehr über die Eigenschaften zu erfahren, nutze die Dokumentation unter dem "Body"-Titel. Eigenschaften, die angegeben werden müssen, sind mit required gekennzeichnet.

    api-properties

    Anstatt den Curl-Befehl zu kopieren, kannst du die Eigenschaften auch aus der Dokumentation unter "Body" übernehmen. Alle Eigenschaften werden dort mit Angabe des Wertes und einer kurzen Beschreibung gelistet.

    Eigenschaft Wert
    Beschreibung der Eigenschaft

    Nutze folgendes Format, um eine Eigenschaft einem Curl-Befehl hinzuzufügen:

    curl \
       -X {request-type} \
       -H "Authorization: Bearer $API_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{"eigenschaft":wert,"eigenschaft":wert,...}' \
       'https://api.hetzner.cloud/v1/{api-url-ending}'

    Die verschiedenen Werte:

    Wert Format
    string "beliebiger-text"
    integer 12
    object {"eigenschaft":wert}
    boolean true
    false
    nullable null
    Beispiel-Request

    Create Resource X

    Body
    name string
    Name of resource
    resource_y integer
    ID of Resource Y which you would like to add to Resource X
    labels object
    User-defined labels (key-value pairs)
      labelkey string
      New label
    delete boolean
    If true, prevents the resource from being deleted
    description string – nullable
    Description of the resource

      Beispiel -d-Zeile im Curl-Befehl:
    -d '{"name":"my-resource","resource_y":18,"labels":{"labelkey":"my-label"},"delete":true,"description":null}'

    Wenn array of ... angegeben wird, kannst du einfach das Format "eigenschaft":[wert] nutzen. Einzelne Werte werden mit einem Komma getrennt:

    array of ... format
    strings ["beliebiger-text","beliebiger-text"]
    integers [12,43]
    objects [{"eigenschaft":wert,"eigenschaft":wert}]

  1. Query-Parameter

    Mit Query-Parametern ist es möglich, die Response auf einen Request zu sortieren oder zu filtern. Du kannst also beispielsweise bestimmen, dass nur Ressourcen mit einem bestimmten Label angezeigt werden sollen.

    Format zum Verfeinern der Ergebnisse:

    • Ein einfacher Query-Parameter

      https://api.hetzner.cloud/v1/{api-url-ending}?parameter=wert

    • Ein Query-Parameter mit einem Enum-Wert
      "enum values" sind vordefinierte Werte, die du direkt kopieren und in die URL einfügen kannst.

      https://api.hetzner.cloud/v1/{api-url-ending}?parameter={enum-value}

    • Zwei oder mehr Querie-Parameter
      Der erste Parameter, der an eine URL angehängt wird, beginnt mit einem Fragezeichen ?. Allen weiteren Parametern wird ein Und-Zeichen & vorgestellt.

      https://api.hetzner.cloud/v1/{api-url-ending}?parameter=wert&parameter=wert

    Wenn du die Response auf einen bestimmten Request sortieren möchtest, nutzt du die Übersicht unter dem Titel "Query Parameters". Dort sind alle Parameter gelistet, die für einen bestimmten Request verfügbar sind.

    api-query-parameters

    Parameter Wert
    Beschreibung des Parameters
    Beispiele
    • Label Selektoren
       Ressourcen können einfache Label besitzen, die lediglich aus dem key-Teil bestehen und sie können key  value -Paare ("key=value") als Label besitzen. Du kannst deine Ressourcen entweder nur nach einem bestimmten "key" sortieren oder nach "key" und "value".
      https://api.hetzner.cloud/v1/floating_ips?label_selector=env
      Mit diesem Request könntest du eine Liste von Ressourcen erhalten, die als Label env  production , env  testing , oder schlicht env besitzen. Weitere Informationen erhältst du in der offiziellen Dokumentation zu Label Selektoren.

    • Sortieren
       Im oberen Beispiel-Bild ist angegeben, dass die Ressourcen nach ID oder nach Erstellungsdatum sortiert werden können. Um die Ergebnisse aufsteigend (engl. ascending asc) nach ID zu sortieren, kannst du einfach den entsprechenden Enum-Wert kopieren.
      https://api.hetzner.cloud/v1/floating_ips?sort=id:asc
      Weitere Informationen erhältst du in der offiziellen Dokumentation zu Sortieren.

    • Zwei Parameter in einem Request
      https://api.hetzner.cloud/v1/floating_ips?label_selector=env&sort=id:asc

  1. Den Curl-Befehl ausführen

    Nachdem du den Curl-Befehl kopiert und bearbeitet hast, stelle sicher, dass auch der richtige API-Token hinzugefügt wurde. Führe den Befehl anschließend über eine Kommandozeile aus.

Nachdem der Befehl ausgeführt wurde, solltest du eine Response erhalten, in der du siehst, ob der Befehl erfolgreich war. Alle Änderungen, die über die API vorgenommen werden, werden auch in der Hetzner Console angezeigt.


Nächste Schritte: