REST API Übersicht

Grundlagen

Die Engagelab REST API ist so konzipiert, dass sie den HTTP- und REST-Spezifikationen entspricht. Beispielsweise wird die GET-Methode für Abfragen und die POST-Methode für Übermittlungen verwendet. Wenn eine Anfrage nicht der entsprechenden HTTP-Methode entspricht, wird ein Fehler zurückgegeben.

Sofern nicht anders angegeben, sollten die Werte der Aufrufparameter als UTF-8 kodiert werden, siehe URL-Codierung.

Datenzentren und Basis-URL

Ab dem 19.03.2025 werden Entwickler:innen, die neu auf die Engagelab Push API zugreifen, gebeten, den folgenden Domainnamen zu verwenden. Die ursprüngliche Basis-URL mit der Endung .cc kann weiterhin genutzt werden, jedoch wird empfohlen, auf den aktuellen Domainnamen umzusteigen.

Bei der Nutzung der REST API muss die gewählte Basis-URL mit dem jeweiligen API-Pfad kombiniert werden, um die vollständige Endpunkt-URL zu erhalten.

              
              {Basis-URL}/{API-Pfad}

            

Hierbei steht {Basis-URL} für die ausgewählte Basis-URL des Datenzentrums und {API-Pfad} für den spezifischen API-Endpunkt, z. B. v4/devices/{registration_id}.

Beispiel:

• Angenommen, das Datenzentrum Singapur wird mit der Basis-URL https://webpushapi-sgp.engagelab.com gewählt.
• Soll beispielsweise die Registrierungsinformation eines bestimmten Geräts gelöscht werden und lautet der API-Pfad v4/devices/{registration_id}, ergibt sich folgender vollständiger API-Endpunkt:

              
              https://webpushapi-sgp.engagelab.com/v4/devices/{registration_id}

            

Dabei steht {registration_id} für die Registrierungs-ID des jeweiligen Geräts.

Auf diese Weise können Sie vollständige API-Endpunkt-URLs für den Zugriff auf verschiedene Datenzentren erstellen.

Authentifizierungsmethode

Die Engagelab REST API verwendet die HTTP-Basisauthentifizierung. Das Grundprinzip besteht darin, den HTTP-Header Authorization wie folgt hinzuzufügen:

              
              Authorization: Basic base64_auth_string

            

Der base64_auth_string wird nach folgendem Algorithmus erzeugt: base64(appKey:masterSecret)
Das heißt, Sie fügen den appKey und den masterSecret mit einem Doppelpunkt getrennt zusammen und kodieren diesen String anschließend mit base64.

Die Parameter appKey und masterSecret finden Sie auf der Seite „Anwendungseinstellungen – Anwendungsinformationen“.

Beispiel für die Authentifizierung

Wenn Ihr appKey „c96f42e0d2e662e45d035ab1“ und Ihr masterSecret „df4d59e84eac2f9d53b36f12“ lautet, verwenden Sie beim Aufruf der Push API v4 den folgenden curl-Befehl:

              
              curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/push \
-H "Content-Type: application/json" \
-u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
-d '{"from":"push","to":"all","body":{"platform":"web","notification":{"alert":"Hi,MTPush !","web":{"alert":"Hi,MTPush !", "title":"web_push", "url":"http://www.google.com","extras":{"web-key1":"web-value1"}}}},"request_id":"12345678", "custom_args":"business info"}'

            

Die HTTP-Anfrage sieht folgendermaßen aus:

              
              > POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==