API Dokumentation

Der Dienst ermöglicht eine automatisierte unidirektionale Kommunikation via Messages-Queues. Der Zugriff erfolgt via REST-API-Schnittstelle.
Bei ComNorm wird der Dienst verwendet, damit ein Online-Shop (Senderseite) eine Softwarelösung (Empfängerseite) über festgelegte Benutzeraktionen (z.B. Artikelwahl) benachrichtigen kann.
Die Verwendung des Dienstes ist nicht zwingend. Eine Softwarelösung kann auch einen eigenen verwenden. Der Notifikations-Mechanismus (Post Message Request) muss aber für die Senderseite identisch funktionieren.

Ablauf

  1. Die Empfängerseite erstellt eine Queue (Create Queue Request) und erhält in der Antwort eine QueueId, eine Notifikations-URL und ein Notification-Secret zurück.
  2. Die Empfängerseite teilt die Notifikations-URL und das Notification-Secret der Senderseite mit (können auch mehrere sein).
  3. Die Senderseite notifiziert Meldungen an die Notifikations-URL unter Angabe des Notification-Secrets (Post Message Request). Der Dienst sammelt so die Meldungen in der Queue.
  4. Die Empfängerseite holt periodisch Meldungen vom Anfang der Queue ab (Peek Messages Request) und verarbeitet diese.
  5. Die Empfängerseite löscht jede verarbeitete Meldung (Delete Message Request). Meldungen rutschen so in der Queue nach.
  6. Die Empfängerseite löscht die Queue (Delete Queue Request), wenn sie nicht mehr benötigt wird.

Allgemeines

Create Queue Request
POSThttps://notification.comnorm.com/api/queues
HeaderX-PARTNER-KEY: {partnerKey}
Response
{
  "queueId": "{queueId}",
  "notificationURL": "{notificationURL}",
  "notificationSecret": "{notificationSecret}"
}
Status200 Ok
Erstellt eine Queue für Meldungsaustausch.
Die zurückgegebene Notifikations-URL entspricht dem API-Einsprung (Post Message Request), um Meldungen zu übertragen.
Das zurückgegebene Notifikations-Secret muss beim Notifikationsaufruf im Header übergeben werden.
Delete Queue Request
HeaderX-PARTNER-KEY: {partnerKey}
DELETEhttps://notification.comnorm.com/api/queues/{queueId}
Status200 Ok
Löscht eine Queue inklusive aller eventuell noch vorhandener Meldungen.
Post Message Request
POSThttps://notification.comnorm.com/api/queues/{queueId}/messages
HeaderX-COMNORM-NOTIFICATION-SECRET: {notificationSecret}
Body{ ... }
Status200 Ok
Fügt eine Meldung zur Queue hinzu.
Es muss ein gültiges JSON-Objekt im Body mitgegeben werden.
Die maximale Objekt-Datengrösse ist auf 16384 Zeichen zu beschränken.
Für den Aufruf ist kein X-PARTNER-KEY erforderlich.
Es muss ein X-COMNORM-NOTIFICATION-SECRET angegeben werden. Dieses wurde beim Erzeugen der Queue (Create Queue Request) generiert.
Peek Messages Request
GEThttps://notification.comnorm.com/api/queues/{queueId}/messages
HeaderX-PARTNER-KEY: {partnerKey}
Parametertimeout={seconds} (optional)
count={number} (optional)
Response
[
  {
    "messageId": "{messageId}",
    "content": { ... }
  },
  ...
]
Status200 Ok
408 Request Timeout
Ermittelt die am Anfang der Queue enthalten Meldungen.
Ist count nicht angegeben, so wird nur die erste Meldung zurückgegeben.
Sind keine Meldungen vorhanden, so kommt ein leeres Array zurück.
Ist timeout > 0 angegeben, so wird mit einer Antwort zugewartet, bis entweder eine Meldung verfügbar ist, oder die Zeit erreicht wird.
Delete Message Request
HeaderX-PARTNER-KEY: {partnerKey}
DELETEhttps://notification.comnorm.com/api/queues/{queueId}/messages/{messageId}
Status200 Ok
Löscht eine Meldung. Diese erscheint nicht mehr in der Queue.