Zweck der REST Report API
Die etracker REST Report API ist eine Schnittstelle, die du nutzen kannst, um eigene Anwendungen mit den Daten aus etracker zu entwickeln oder um die Daten im eigenen Unternehmen weiter zu verarbeiten.
Zugang zur REST Report API
Die Rest Report API steht dir in der etracker Analytics Enterprise Edition zu Verfügung. Zur Nutzung benötigst du einen sog. Developer Token. Diesen kannst du bei unserem Customer Service anfordern. Schicke hierzu bitte eine E-Mail an service@etracker.com, in der du uns eine gültige E-Mail-Adresse mitteilst. Mit dieser E-Mail-Adresse und dem Developer Token bist du dann berechtigt, über die etracker REST Report API auf Daten aus etracker zuzugreifen.
Die E-Mail-Adresse und der Developer Token sind in jeder Web Service Anfrage (Request) innerhalb des Anfrage-Headers mitzuliefern.
Hinweis:
Zum Schutz der Privatsphäre sowie zur Vermeidung einer unberechtigten Nutzung der etracker Web Services API, sollte der Developer Token in jedem Fall geheim gehalten werden.
Nutzung der REST Report API
Um die Nutzung der etracker REST Report API zu erleichtern, empfehlen wir die Verwendung eines REST-Clients. Die Ausgestaltung des Clients hängt von der eingesetzten Programmiersprache ab. Der Client sendet die Anfragen an den Service und gibt definierte Werte zurück, die anschließend weiterverarbeitet werden können.
Außer einer Entwicklungsumgebung für die verwendete Programmiersprache wird keinerlei weitere Software oder Installation auf deinem System benötigt.
Aufbau der URL für die REST-Calls
Die etracker REST-API nimmt ausschließlich Calls über https entgegen. Alle in diesem Dokument beschriebenen Calls sind GET-Abfragen. Die Adresse des etracker REST-Servers ist ws.etracker.com und die Basis-URI für alle Abfragen ist /api/v6.
Die REST-Calls können mit oder ohne Parameter geschrieben sein. REST-Calls zum Abrufen von Report-Daten ohne Parameter werden jedoch nicht empfohlen, da unter Umständen sehr große Datenmengen zurückgegeben werden. Bei den Parametern wird nicht nach Groß- und Kleinschreibung unterschieden.
Beispiel mit Parametern zum Abrufen von Daten aus dem Report ‚Gerät‘:
https://ws.etracker.com/api/v6/report/EADeviceType/data?limit=401
Das gleiche Beispiel ohne Parameter (nicht empfohlen):
https://ws.etracker.com/api/v6/report/EADeviceType/data
Rückgabewerte
Das Format der Rückgabewerte von etracker REST Report API-Abfragen ist entweder JSON oder CSV. CSV wird nur bei der Abfrage von Report-Daten unterstützt und kommt nur dann zurück, wenn das Format explizit abgefragt wird. Bei den JSON-Rückgaben kommt immer ein JSON-Array oder -Objekt zurück, auch dann, wenn nur ein Wert zurückgegeben wird.
Die etracker REST Report API arbeitet mit der Kodierung UTF-8. Alle Daten, die die API liefert oder entgegennimmt, müssen in UTF-8 kodiert sein. Sonderzeichen wie Umlaute werden teilweise in Form von JavaScript Escape-Sequenzen zurückgegeben. Ein ‚ä‘-Zeichen wäre dann z. B. ‚\u00e4‘ in den Rückgabedaten. Die meisten JSON-Parser wandeln solche Escape-Sequenzen automatisch in Buchstaben um.
Authentifizierung
Jede REST Report-Anfrage muss zur Authentifizierung mit einem Header versehen werden.
Folgende Header-Informationen sind zwingend notwendig:
- X-ET-email: Dieses Header-Element enthält die E-Mail-Adresse des Entwicklers, der Zugriff auf die API hat.
- X-ET-developerToken: Dieses Header-Element enthält den Developer Token, der beim Customer Service angefordert werden muss.
- X-ET-accountId: Dieses Element enthält die etracker Account-Id. Für die Authentifizierung kann auch ein etracker Mitbenutzer angegeben werden (Format: #accountId#-#subuserId#)
- X-ET-password: Dieses Element enthält das Passwort des etracker Accounts.
Beispiel:
X-ET-email=qa@etracker.com X-ET-developerToken=ab7891ca89d9b4d10dc1703a7f0214256babe6c9 X-ET-accountId=18854 X-ET-password=demo
Im Firefox kannst du z.B. die Erweiterung Modify Headers verwenden, um diese Header mitzusenden.