REST API & Drivers
      Zurück zur Startseite
      1. Xelon Docs
      2. Plattform Info
      3. REST API & Drivers

      Xelon API 101

      Genau wie Sie lieben wir es, Dinge zu entwickeln und zu automatisieren. Aus diesem Grund unterhalten wir eine öffentliche REST-API, die es Entwicklern ermöglicht, Xelon HQ-Daten über HTTP-Anfragen abzurufen und zu verarbeiten.

      Wenn Sie bereits Erfahrung mit dem Erstellen von REST API-Calls haben, können Sie diesen Abschnitt gerne überspringen.

      Wenn REST APIs neu für Sie sind, ist diese Seite ein guter Ausgangspunkt. Wir werden Sie mit einer einfachen Xelon HQ API-Anfrage anleiten: die Tenant-ID abrufen.

      Führen Sie Ihren ersten API-Call durch

      So starten Sie in drei einfachen Schritten:

      1. Registrieren Sie sich bei Postman (ein Tool, das wir später noch brauchen)
      2. Registrieren oder loggen Sie sich beim Xelon HQ ein
      3. Öffnen Sie diese URL: https:/hq.xelon.ch/api/service/tenant

      Herzlichen Glückwunsch! Das war Ihre erste Xelon HQ API-Anfrage. Lassen Sie uns nun genauer betrachten, was gerade passiert ist.

      Die Basis-URL für alle unsere API-Anfragen lautet https://hq.xelon.ch/api/service/. Wir wollen Daten von unserer Homepage abrufen, also gehen wir eine Ebene tiefer zu https://hq.xelon.ch/api/service/tenant.

      Derselbe Pfadalgorithmus funktioniert für Tenant-IDs, virtuelle Maschinen-IDs und andere Instanzen.

      Authentifizieren Sie sich

      Wir haben auch eine strukturierte JSON-response, erhalten, aber es wird ein  UNAUTHORIZED_REQUEST-Fehler angezeigt. Lassen Sie uns herausfinden, warum das passiert und wie man es beheben kann.

      Erhalten Sie einen Service-Token

      Ähnlich wie bei der Eingabe Ihrer E-Mail-Adresse und Ihres Passworts auf unserer Website müssen Sie sich authentifizieren, wenn Sie auf Xelon HQ-Daten über die API zugreifen möchten. Die einfachste Methode besteht darin, einen Service-Token zu erhalten, den Sie als Ihr eindeutiges Passwort für den Zugriff auf unsere API betrachten können.

      Nachdem Sie sich bei Xelon HQ angemeldet haben:

      1. Gehen Sie zu Manage My Organization und klicken Sie auf den grünen Add Service Knopf auf der rechten Seite
      2. Geben Sie den Namen des Dienstes ein (um anderen bei der Identifizierung des Erstellers zu helfen) und Ihre IP-Adresse
      3. Wenn Sie fertig sind, klicken Sie auf Add new service und Copy, um den Token zu kopieren

      Create service token.gif

      Behandeln Sie Ihren Service-Token wie das Passwort für Ihr Bankkonto.

      Erstellen Sie einen Request über Postman

      Wichtig

      Wenn Sie das Postman Web-Interface (über Ihren Browser) verwenden, stimmt Ihre IP-Adresse möglicherweise nicht mit Ihrer Postman Web-IP-Adresse überein. Um die richtige IP-Adresse zu erhalten, wenn Sie Postman Web verwenden, führen Sie einen GET-Aufruf an https://ifconfig.io/ip durch, um die benötigte IP-Adresse abzurufen.

      Für einen curl Request sollter ihr Bearer-type Service Token als --header Parameter gesendet werden. Beispiel: curl --location --request GET 'https://vdc.xelon.ch/api/service/tenants' \ --header 'Authorization: Bearer <TOKEN>'

      Nachdem wir uns authentifiziert haben, können wir unsere API-Anfrage erneut stellen:
      1. Im Postman Interface,gehen Sie zu File > New > HTTP Request
      2. Wählen Sie GET als Ihre Methode und fügen Sie die folgende URL ein: https://hq.xelon.ch/api/service/tenants
      3. Wählen Sie den Authorization Tab > Type Block > Bearer token und geben Sie Ihren Service Token ein
      4. Klicken Sie auf den blauen Send Button

      postman_request.gif

      Am unteren Ende Ihres Postman-Fensters sehen Sie eine JSON-Antwort – darauf werden wir im nächsten Abschnitt näher eingehen. 

      Wenn Sie bei einer Anfrage eine Fehlermeldung erhalten, überprüfen Sie Ihr Service-Token oder die verknüpfte IP-Adresse.

      Die Antwort interpretieren

      In der Antwort sehen Sie eine Reihe von Tenants –jeder mit einem individuellen namen und id. Innerhalb Ihrer Tenant-Reihe, können Sie Ihre individuelle Tenant id sehen.

      tenant response decypher.png

      Gut gemacht, Sie haben Ihren ersten API-Aufruf durchgeführt und eine Tenant id abgerufen!

      Unsere API ist dokumentiert, um aufzuzeigen, welche Ressourcen verfügbar sind und welche Art von Rückgabedaten zu erwarten ist. Zum Beispiel hier ist die Dokumentation für den Tenants-Endpunkt, den wir gerade aufgerufen haben.

      Entdecken Sie die Möglichkeiten der Xelon HQ API auf developers.xelon.ch.

      Einen Call durch das Terminal durchführen 

      Anstelle von Postman können Sie auch über das Terminal arbeiten - mit einem vorinstallierten Befehlszeilenprogramm namens cURL, das bei macOS gebündelt ist, aber auch für Windows verfügbar ist.

      Beginnen wir:

      1. Öffnen Sie ein Terminal (Mac und Windows Anleitung)
      2. Fügen Sie den folgenden Code ein (stellen Sie sicher, dass Ihr Token vorhanden ist)
      3. Drücken Sie Enter
      curl --location --request GET 'https://hq.xelon.ch/api/service/tenants' \
      --header 'Authorization: Bearer <YOUR TOKEN GOES HERE>'

      Wenn alles korrekt ist, erhalten Sie dieselbe Antwort wie in Postman. Allerdings erleichtert Postman das Scannen und Verstehen der Antwort.

      curl call.gif

      Sie sind bereit, mit dem Programmieren zu beginnen! In unserer API-Referenzdokumentation verwenden wir häufig cURL-Befehle als Beispiele. Es ist benutzerfreundlich genug und funktioniert auf allen Plattformen.


      Einen Service Token löschen

      Manchmal müssen Sie einen neuen Token für Ihre IP-Adresse generieren oder den aktuellen entfernen. So geht's:

      1. Gehen Sie zur Manage My Organization Seite
      2. Suchen Sie innerhalb des Service-Token-Blocks Ihren Token und klicken Sie auf Delete
      3. Klicken Sie Confirm um den Token permanent zu löschen

      delete service token.gif

      Achtung

      Eine Löschung des Service-Token kann nicht rückgängig gemacht werden. Stellen Sie sicher, dass das Token nicht von Ihrem Team für API-Aufrufe verwendet wird, bevor Sie es löschen.