API

Bei der API handelt es sich um eine REST-API. Das ist ein weit verbreiter Webstandard, der sich durch Zustandslosigkeit, deskriptive und einheitliche Methoden und Unterstützung für HTTP-Caching auszeichnet.

Weitere Informationen: Wikipedia: Representational State Transfer

Die genaue URL der Swagger-Dokumentation unserer API-Schnittstelle finden Sie unter Einstellungen in der rechten oberen Ecke Ihres Accounts.

Grundlagen

Jede API-Anfrage besteht aus einer Base-URL und einer Methode. Die Base-URL ist im oberen Bereich der ATLAS API-Dokumentation zu finden.

Es gibt vier Arten von API-Methoden: GET, POST, PUT, DELETE.

• GET: Wird verwendet, um Informationen abzufragen. Hier werden alle Parameter der Anfrage in der URL übermittelt.
• POST: Wird verwendet, um einen Datensatz anzulegen und mit Informationen zu füllen. Hier können Parameter im Body der Anfrage im JSON-Format übertragen werden.
• PUT: Wird verwendet, um einen bestehenden Datensatz zu aktualisieren.
• DELETE: Wird verwendet, um einen Datensatz zu löschen.

In der Swagger-Dokumentation sind alle verfügbaren API-Methoden aufgelistet und die Parameter spezifiziert. Für Fragen wenden Sie sich bitte an den Support

Bei jeder API-Methode wird ein Pfad angegeben. Diesen müssen Sie an ihre Base-URL anhängen um Anfragen senden zu können.

Authentifizierung

Bevor Sie allerdings Anfragen über die API an die Plattform schicken können, müssen Sie sich authentifizieren.

Hierfür muss der Pfad /auth verwendet werden. Die genauen Parameter dazu sind in der Swagger-Dokumentation im authentication-controller spezifiziert.

Sie senden Ihre Anmeldedaten an den API-Endpoint, dieser schickt Ihnen darauf einen Token zurück. Der Token muss bei Anfragen an andere Methoden dann immer im Header angeben werden.

Nachfolgend ein Beispielheader für eine HTTP-Anfrage:

Authorization: Bearer TOKEN

TOKEN ersetzen Sie durch jenen, welchen Sie vom authentication-controller bekommen.

Wenn Sie nur einmalig einen Token erstellen und weiter verwenden wollen, bietet sich auch die "Try it out" Funktion an.

Um die API weiterhin über dieses Webinterface zu testen, klicken Sie oben rechts auf den Button Authorize und geben in das Textfeld "Bearer " (das Leerzeichen ist wichtig), gefolgt von dem Token den Sie zuvor erhalten haben, ein. Nach einem Klick auf Authorize, sind alle zukünftigen Anfragen, die über dieses Webinterface gestellt werden, authentifiziert.

Beispiel: Websockets

Beispiel: Zugriffsmöglichkeiten für Websockets

Durch Klicken auf eine bestimmte Methode (farbig hinterlegt: "GET", "PUT", "POST", "DELETE") sind weitere Infos zu deren Parametern und möglichen Rückgabetypen sowie Beispiele ersichtlich.

Oben sehen Sie den Typ (in diesem Fall GET) und den Pfad der Methode (in diesem Fall /websockets). Unter Parameters sehen Sie die Parameter, die in einer Anfrage übergeben werden können. Notwendige Parameter sind mit einem roten Stern markiert, alle anderen sind optional. Um die Methode nun aufzurufen, müssen Sie den oben angebenen Pfad an die Base-URL (siehe oben) hängen. Bei einer GET Anfrage werden dann dahinter noch die Parameter gesetzt.

Um alle Websockets der Firma mit der ID "1234" zu ermitteln, ergibt sich folgende URL:

[ATLAS-BASE-URL]/websocket?companyId=1234

Nachfolgend sehen Sie, welche Daten die Methode zurückgeben wird. Meist treten einer oder mehrere Errorfälle und ein Erfolgsfall auf. Beim Erfolgsgfall werden sowohl Beispieldaten als auch das genaue Modell des Rückgabewertes angegeben.

Beispiel für das Modell des Rückgabewertes von /websockets