API-Dokumentation – Hauptanwendung

Einleitung

API steht für Application Programming Interface (Anwendungsprogrammierschnittstelle). Eine API ermöglicht Ihnen die programmgesteuerte Interaktion mit bestimmten Teilen von RESPONSUM und den Austausch von Informationen. RESPONSUM bietet API-Endpunkte für Kernfunktionen/Daten, die für bestimmte Automatisierungen und Integrationen mit anderen (operativen) Systemen/Tools nützlich sein können.

Diese API-Endpunkte werden im Laufe der Zeit aktualisiert/erweitert, aber wir stellen sicher, dass sie abwärtskompatibel bleiben, damit erstellte Integrationen weiterhin funktionieren. Wenn Sie Fragen oder Anfragen zu neuen Endpunkten haben, kontaktieren Sie uns bitte über support@responsum.eu.

Schnellstart

  1. Stellen Sie sicher, dass APIs für Ihren Tenant aktiviert sind. Sie sind standardmäßig deaktiviert, daher müssen Sie möglicherweise support@responsum.eu kontaktieren.
  2. Nach der Aktivierung können Sie unter Einstellungen > Setup > Meine Organisation Ihren „Tenant-Schlüssel“ in den Eigenschaften finden, indem Sie sich durch die oberste Ebene klicken.
  3. Die Dokumentation finden Sie nun unter Einstellungen > Integrationen > API-Dokumentation.
  4. Erstellen Sie ein API-Token, indem Sie zu Einstellungen > Integrationen > API-Tokens navigieren.
  5. Es sind einige Node.JS JavaScript-Codebeispiele hier verfügbar: https://github.com/RESPONSUM-BE/RESPONSUM-api-example – Sie können den zuvor generierten Tenant-Schlüssel + API-Token verwenden, um es auszuprobieren.
  6. Sie finden ein Diagramm in unserem Help Center, das die Hauptkonzepte in RESPONSUM erklärt. Dies hilft Ihnen, unsere grundlegende Struktur zu verstehen, damit Sie Konzepte leicht wiederfinden können.
  7. Hier ist eine kurze Einführung in einige wichtige Konzepte – Sie können unten mehr darüber lesen.
    1. UUIDs: Sie können Ihre eigenen UUIDs erstellen oder RESPONSUM-formatierte UUIDs mit https://api.responsum.app/v1/[tenant key]/uuids/[amount] generieren. – Wenn Sie Ihre eigenen UUIDs generieren, stellen Sie bitte absolut sicher, dass sie 100 % eindeutig sind. Es gibt Bibliotheken, falls Sie diese benötigen, verwenden Sie nicht math.random 🙂
    2. Link-Objekte: RESPONSUM verwendet KEINE typische beziehungsbasierte Modellierung. Links zwischen Elementen sind für uns Objekte.
    3. Versionierung: Fast alle RESPONSUM-Modelle sind versioniert. Das bedeutet, wir verfolgen Änderungen für alles. Es gibt spezielle APIs, um dies zu handhaben oder Informationen über die Versionshistorie und Genehmigung eines Objekts anzufordern.
    4. Berechnete Felder: RESPONSUM berechnet serverseitig eine Reihe von Feldern. Dies geschieht automatisch. Beim Abrufen eines Objekts erhalten Sie auch unsere berechneten Felder. Sie können diese nicht manuell aktualisieren.
    5. Ereignisgesteuert: Alles, was in RESPONSUM geschieht (Erstellen, Aktualisieren, Löschen, Versionieren, …), beginnt als Ereignis. Sie können Webhooks verwenden, um alle Arten von Ereignissen zu abonnieren. Im Wesentlichen kann auf alles, was in RESPONSUM geschieht, mithilfe von Webhook-APIs reagiert werden.
  8. Es wird immer empfohlen, das vollständige Handbuch zu lesen, bevor Sie loslegen. Es ist eine gefährliche Welt da draußen, und Sie wollen sich nicht verletzen – aber mit diesem Schnellstart hoffe ich, dass Sie es schaffen. Viel Glück da draußen!

Erste Schritte

Sicherstellen, dass die API für Ihren Tenant aktiviert ist

Standardmäßig ist die RESPONSUM API auf Tenant-Ebene deaktiviert und in unserer Benutzeroberfläche ausgeblendet.

Um die API für Ihren Tenant zu aktivieren, müssen Sie unser Support-Team unter support@responsum.eu kontaktieren. Dieses kann die API aktivieren und auch Fragen beantworten, die Sie nach dem Lesen der verfügbaren Dokumentation noch haben könnten, und Sie mit den richtigen Ansprechpartnern für technischere Fragen, Diskussionen oder Implementierungsanfragen in Kontakt bringen.

Alle weiteren Dokumentationen gehen davon aus, dass die RESPONSUM API für Ihren Tenant aktiviert wurde.

Ihr Tenant-Schlüssel

Bei der Verwendung der RESPONSUM API müssen Sie bei jeder Anfrage Ihren tatsächlichen Tenant-Schlüssel verwenden, wie er in unserem System definiert ist. Dieser Tenant-Schlüssel kann in der Anwendung gefunden werden, indem Sie zu Einstellungen > Setup > Meine Organisation navigieren und dort die höchste Organisationseinheit öffnen, da diese Ihren Tenant widerspiegelt.

In den Details der Tenant-„Metadaten“ (zwei Pfeile nach unten oben im Seitenbereich) finden Sie das schreibgeschützte Feld „Tenant-Schlüssel“.

Dieser Tenant-Schlüssel wurde bei der Erstellung Ihres Tenants festgelegt und kann im Gegensatz zum Tenant-Namen nicht geändert werden und ist für diesen spezifischen Tenant eindeutig.

OpenAPI-Spezifikationen für die API Ihres Tenants

Die RESPONSUM API, die Sie verwenden werden, wird speziell für Ihren Tenant generiert und enthält alle Anpassungen (benutzerdefinierte Felder, benutzerdefinierte Beziehungen, Geschäftsregeln…), die möglicherweise vorgenommen wurden. Daher können die bereitgestellten Modelle zwischen den Tenants variieren.

Zur Vereinfachung der Integration stellen wir eine Spezifikations-JSON-Datei gemäß den OpenAPI-Spezifikationen bereit. Sie können diese laden, indem Sie den [Tenant-Schlüssel] in der folgenden URL durch Ihren zuvor gefundenen Tenant-Schlüssel ersetzen: https://api.responsum.app/v1/[tenant key]/spec.json.

Wir bieten auch eine visuelle Dokumentation basierend auf dieser Spezifikationsdatei an, um einfache Tests zu ermöglichen, während Sie sich mit der API vertraut machen. Diese finden Sie in unserer App, wenn Sie zu Einstellungen > Integrationen > API-Dokumentation navigieren.

Die erste Anfrage in dieser API-Dokumentation dient auch dazu, die OpenAPI-Spezifikationen abzurufen, und ist eine der wenigen Anfragen, die Sie ohne Authentifizierung durchführen können.

Authentifizierung & Autorisierung

Alle funktionalen Anfragen an die RESPONSUM API erwarten, dass ein API-Token als Teil der Anfrage übergeben wird. Dies dient sowohl der Authentifizierung (durch Überprüfung des Tokens selbst) als auch der Autorisierung (durch Überprüfung der Berechtigungen des mit diesem Token verknüpften Benutzerkontos) (der Link zur Benutzerberechtigungsstufe).

Alle über die API mit diesem Token durchgeführten Aktionen werden auch als vom mit dem API-Token verknüpften Benutzer ausgeführt protokolliert. Somit imitieren Sie diesen Benutzer, indem Sie das API-Token verwenden.

Erstellen eines API-Tokens

API-Tokens können nur über unsere App verwaltet werden, indem Sie zu Einstellungen > Integrationen > API-Tokens navigieren.

Ein API-Token besteht aus:

  • Einem Namen, um es in der Liste leichter zu erkennen und die Tokens voneinander zu unterscheiden;
  • Einem Token-String, der für Sie generiert und bei jeder Anfrage an die API verwendet wird;
  • Einer Benutzerberechtigungsstufe, die mit einem Benutzerkonto verknüpft ist, das bei Verwendung dieses API-Tokens imitiert wird. Wenn Sie also diesem API-Token Berechtigungen erteilen oder verweigern möchten, tun Sie dies, indem Sie sie dem hier verknüpften Benutzerkonto erteilen oder verweigern;
  • Einem Ablaufdatum. Wenn dieses festgelegt ist, funktioniert das Token nach diesem Datum nicht mehr.

Nach der Erstellung sollte der Token-String eines API-Tokens sofort zur Verwendung verfügbar sein. Wenn Ihr Token-String aus irgendeinem Grund kompromittiert wird, wird durch das erneute Generieren des Token-Strings und das Speichern des aktualisierten API-Tokens der alte Token-String sofort ungültig.

Übergeben des API-Tokens mit Anfragen

Sobald Sie einen gültigen API-Token-String haben, können Sie ihn an die RESPONSUM API übergeben, indem Sie Ihren Anfragen einen zusätzlichen Header hinzufügen Api-Token, dessen Wert Ihr API-Token-String ist.

Dienstprogrammanfragen

UUIDs

Es gibt verschiedene Standards für Universally Unique IDentifiers, die derzeit verwendet werden, und die RESPONSUM API sollte die meisten akzeptieren, da unsere Validierung aus Folgendem besteht:

  • Mindestens 5 Zeichen lang
  • Besteht nur aus den Zeichen:
    • a bis z: abcdefghijklmnopqrstuvwxyz
    • 0 bis 9: 0123456789
    • Bindestrich: -

Des Weiteren erwarten wir, dass die UUID eindeutig ist, werden dies aber nur begrenzt überprüfen, in dem Sinne, dass der Versuch, ein neues Modell oder Links mit einer UUID zu erstellen, die für dieses spezifische Modell oder diesen Link bereits existiert, einen Fehler zurückgibt.

RESPONSUM selbst verwendet eine Variante des cuid2-Algorithmus, die so modifiziert wurde, dass sie leichter zu erkennen ist und unserem bevorzugten Format entspricht.

Um Ihnen die Verwendung von UUIDs im RESPONSUM-Format zu erleichtern, haben wir einen API-Endpunkt hinzugefügt, mit dem Sie zwischen 1 und 1000 UUIDs generieren können, die garantiert eindeutig und von den intern von RESPONSUM generierten nicht zu unterscheiden sind.

Ersetzen Sie den Tenant-Schlüssel und den Betrag in https://api.responsum.app/v1/[tenant key]/uuids/[amount] und führen Sie eine GET-Anfrage damit aus, wobei Sie sicherstellen, dass der Api-Token Header enthalten ist. Als Rückgabewert erhalten Sie ein JSON-Array, das die UUIDs als String-Werte enthält.

Das Beispielprojekt enthält eine Beispieloperation, die dies tut: https://github.com/RESPONSUM-BE/RESPONSUM-api-example/blob/main/src/operations/getUuids.ts

Links in RESPONSUM werden etwas anders gehandhabt als die meisten gängigen Lösungen, da jeder Link als eigenes Objekt in der Link-Sammlung gespeichert wird, das auf die verschiedenen miteinander verknüpften Modelle verweist, anstatt dass Referenzen an den Modellen auf andere Modelle verweisen.

Links werden auch nie aktualisiert; sie können nur erstellt oder gelöscht werden, da das Ändern eines verknüpften Modells als Löschen des alten Links und Erstellen eines neuen Links betrachtet wird.

Alle Links basieren auf verschiedenen Link-Definitionen, von denen einige fest codiert sind und einige vom Benutzer benutzerdefiniert erstellt werden können. Wenn Sie die Link-Definitionen über den GET https://api.responsum.app/v1/[tenant key]/link-definitions Endpunkt abrufen, erhalten Sie ein JSON, das ein großes Objekt enthält, das als Wörterbuch aller Link-Definitionen angesehen werden kann.

Ein Beispiel-Snippet als Referenz:

{
  "stakeholder-stakeholderContact-contacts": {
    "stakeholder": {
      "modelType": "stakeholder",
      "oneOrMany": "one",
      "isRequired": false,
      "relationBehaviour": "reference-same-object"
    },
    "contact": {
      "modelType": "stakeholder-contact",
      "oneOrMany": "many",
      "isRequired": false,
      "relationBehaviour": "reference-same-object"
    }
  },
  <snipped-for-size>
}

Ein linkType ist ein eindeutiger beschreibender Schlüssel für diese spezifische Link-Definition. In diesem Beispiel sehen Sie, dass jeder Objektschlüssel („stakeholder-stakeholderContact-contacts“) der linkType der spezifischen Link-Definition ist.

Eine Rolle ist ein beschreibender Schlüssel, der innerhalb der Link-Definition eindeutig ist, um die verschiedenen Zweige der Link-Definition zu identifizieren. In diesem Fall sind „stakeholder“ und „contact“ die beiden Rollen, wie Sie sehen können, müssen diese nicht mit dem Modelltyp übereinstimmen. Ein weiteres Beispiel für einen selbstreferenziellen Link ist, dass diese Rollen „parent“ und „child“ sein könnten.

Beachten Sie auch, dass die meisten Links nur zwei Zweige haben, aber mehr als zwei erlaubt sind und wir bereits mindestens einen Fall haben, bei dem wir Drei-Wege-Links haben.

Unter der Rolle haben Sie eine Zweigdefinition, die einige Eigenschaften dieses speziellen Zweigs beschreibt:

  • Der modelType beschreibt, welche Modelltypen erlaubt sind, dies kann sein:
    • Ein einzelner Modelltyp
    • Ein Array von Modelltypen
    • Die Konstante „all-models“
  • Der oneOrMany beschreibt, ob nur ein Link zu dieser Modelltyp- & UUID-Kombination erlaubt sein sollte oder ob es viele geben kann.
  • Der isRequired beschreibt, ob dieser Link auf dieser Seite des Links erforderlich ist. Wenn wahr, sollte jedes Modell des/der in modelType definierten Typs/Typen mindestens einen Link dieses linkType haben.
  • Das relationBehaviour wird hauptsächlich intern verwendet, um zu entscheiden, was mit diesem Link beim Duplizieren von Modellen geschehen soll.

Basierend auf der obigen Link-Definition finden wir dieselbe in tatsächlichen Links wieder.

Ein Beispiel für ein Link-Objekt könnte wie folgt aussehen:

{
  "uuid": "0fc0ea83-88df-49ec-a681-1ced0a6c0683",
  "type": "link",
  "linkType": "stakeholder-stakeholderContact-contacts",
  "links": [
    {
      "modelType": "stakeholder",
      "modelUuid": "55092a14-4d95-4665-ac50-eb687e535222",
      "role"     : "stakeholder"
    },
    {
      "modelType": "stakeholder-contact",
      "modelUuid": "ad95eded-3168-4a12-968d-456bc031af7e",
      "role"     : "contact"
    }
  ]
}

Die Eigenschaften uuid und type „link“ sind immer auf jedem Objekt vorhanden, um es eindeutig zu identifizieren.

Der linkType stimmt mit einer der Link-Definitionen überein, in diesem Fall mit der im Link-Definitionen-Beispiel.

Die Link-Eigenschaften sind ein Array der verschiedenen Zweige. Die Anzahl der Elemente in diesem Array stimmt immer mit der Anzahl der Rollen in der Link-Definition überein, da wir für jede Rolle ein verknüpftes Modell erwarten.

  • Die Rolle stimmt mit einer der Rollen überein, wie sie in der passenden Link-Definition definiert ist.
  • Der modelType stimmt mit einem der erlaubten Modelltypen für die passende Link-Definition und Rollen-Definition überein.
  • Die uuid identifiziert dann, welches spezifische Modell des gegebenen Modelltyps dieser Link referenziert.

Des Weiteren kann es auch eine metaData-Eigenschaft geben, die ein freiformatiertes Datenobjekt mit zusätzlichen Metadaten zu diesem spezifischen Link enthalten kann, obwohl dies selten verwendet wird.

Meistens erhalten Sie Links als Teil von Modellen und erstellen oder ändern Links beim Erstellen oder Aktualisieren von Modellen.

Eine Link-Eigenschaft an einem Modell wird, wenn sie ausgefüllt ist, als die neue Liste von Links für diese Eigenschaft betrachtet, die alle bereits vorhandenen Links für die Eigenschaft dieses Modells ersetzt. Wenn Sie also einen neuen Link zu einem Modell hinzufügen, stellen Sie sicher, dass Sie auch alle vorhandenen Links einschließen, die Sie behalten möchten.

Daneben gibt es auch drei Endpunkte, um direkt mit Links zu interagieren.

Der GET https://api.responsum.app/v1/[tenant key]/links Endpunkt ermöglicht es Ihnen, alle Links nach mehreren Filtern abzurufen:

  • uuids, die UUIDs der Link-Objekte
  • model-uuids, die UUIDs der in den Link-Objekten referenzierten Modelle
  • relation-names, die LinkTypes der Link-Objekte

Diese können als URI-kodierte Abfrageparameter bereitgestellt werden, die ein JSON-String-Array als Werte enthalten.

Der POST https://api.responsum.app/v1/[tenant key]/create Endpunkt, obwohl hauptsächlich zum Erstellen von Modellen verwendet, akzeptiert auch Link-Objekte und kann somit zum Erstellen neuer Links verwendet werden.

Der DELETE https://api.responsum.app/v1/[tenant key]/link Endpunkt ermöglicht es Ihnen, einen oder mehrere Links direkt zu löschen, für die Sie die UUID des Link-Objekts kennen.

Modellanfragen

Alle Daten in RESPONSUM werden in Modellen gespeichert, daher werden die meisten API-Operationen auf diese Modelle ausgerichtet sein.

Jedes Modell muss eine type und uuid haben, die beide erforderlich sind und nach der Erstellung nicht geändert werden können.

Der Typ ist eines unserer vordefinierten Modelle, wie z. B. „processing-activity“ oder „risk“.

Modell-Definition

Dies bezieht sich auf eine Modell-Definition mit allen verfügbaren Feldern, einschließlich der in der Anwendung definierten benutzerdefinierten Felder. Für type enthält es den erwarteten Typ als String; stellen Sie sicher, dass Sie genau diese String-Werte verwenden.

Für Basisfelder enthält es deren Datentyp und ob sie erforderlich sind oder nicht.

Für Link-Felder enthält es ein Array von Link-Objekten.

Modelle auflisten

Für jeden Modelltyp haben wir einen separaten GET-Endpunkt in der API, um alle oder eine gefilterte Liste von Modellen für diesen Typ abzurufen.

Zum Filtern können Sie einen URI-kodierten Abfrageparameter „param-filter“ zur GET-URL hinzufügen, der ein JSON-Objekt mit dem Filter enthält. Dieser Filter hat als Eigenschaft den Namen der Eigenschaft, nach der Sie filtern möchten, und als Wert ein Array aller Eigenschaftswerte, die Sie abgleichen möchten.

Wenn Sie beispielsweise „advice“ filtern möchten, um Modelle zu finden, deren Status „new“ oder „ongoing“ ist, würden Sie ein JSON-Filterobjekt wie folgt erstellen: {"status": ["new", "ongoing"]}. Danach kodieren Sie es als Wert für den Abfrageparameter „param-filter“ in der URI, was Ihnen eine GET-Anfrage wie folgt ergibt: https://api.responsum.app/v1/[tenant key]/advice?param-filter=%7B%22status%22%3A%20%5B%22new%22%2C%20%22ongoing%22%5D%7D

Sie können Filter auch auf mehrere Eigenschaften kombinieren, indem Sie dem JSON-Filterobjekt zusätzliche Eigenschaften hinzufügen, wie hier: {"status": ["new", "ongoing"], "isObsolete": [false]}. Dies gibt ein Array passender Modelle oder ein leeres Array zurück, wenn keine Modelle gefunden werden.

Das Beispielprojekt enthält eine Beispieloperation, die dies tut: https://github.com/RESPONSUM-BE/RESPONSUM-api-example/blob/main/src/operations/getCountriesByFilter.ts

Ein einzelnes Modell abrufen

Für jeden Modelltyp haben wir einen separaten GET-Endpunkt in der API, um ein spezifisches Modell dieses Typs basierend auf seiner UUID abzurufen. Hängen Sie einfach die UUID an die Modelltyp-URL an, was Ihnen eine GET-Anfrage wie folgt ergibt: https://api.responsum.app/v1/[tenant key]/advice/raou8qtt-60od-n7t5-g8el-c0sy99r0ppag

Dies gibt das einzelne Modell oder einen 404-Fehler „no model found“ zurück.

Um Modelle und Links zwischen diesen Modellen zu erstellen, haben wir einen generischen POST https://api.responsum.app/v1/[tenant key]/create Endpunkt, da wir es ermöglichen möchten, eine Reihe von mehreren verwandten Modellen und die Links zwischen ihnen in einem Durchgang zu erstellen, um die Wahrscheinlichkeit von partiellen Sätzen aufgrund fehlgeschlagener Validierung oder Ähnlichem zu reduzieren.

Der Erstellungs-Endpunkt akzeptiert ein Array von Modellen, von denen jedes den Typ, eine UUID und alle erforderlichen Eigenschaften für diesen Modelltyp haben sollte.

Für die Link-Eigenschaften an den Modellen können Sie auch ein Array von Link-Objekten einschließen, von denen wir die Vereinigung über die bereitgestellten Modelle hinweg nehmen und diese dann einfügen. Das bedeutet, dass, wenn Sie zwei Modelle haben, die miteinander verknüpft sind, unsere API nur das Link-Objekt benötigt, das diese beiden an einem der Modelle verbindet, um zu verstehen, dass es hinzugefügt werden sollte. Das Hinzufügen an beiden Modellen macht jedoch keinen Unterschied.

Das Beispielprojekt enthält eine Beispieloperation, die dies tut.

Um Modelle und Links zwischen diesen Modellen zu aktualisieren, haben wir einen generischen PATCH https://api.responsum.app/v1/[tenant key]/update Endpunkt, da wir es ermöglichen möchten, eine Reihe von mehreren verwandten Modellen und die Links zwischen ihnen in einem Durchgang zu aktualisieren.

Der Update-Endpunkt akzeptiert ein Array von Modellen, von denen jedes nur den Typ, die UUID und die zu aktualisierenden Felder haben sollte.

Für die Link-Eigenschaften an den Modellen handelt es sich wiederum um ein Array von Link-Objekten, von denen wir die Vereinigung über die bereitgestellten Modelle hinweg nehmen und dann alle Links löschen, die nicht Teil dieser Vereinigung sind, bevor wir alle Links in dieser Vereinigung hinzufügen, die noch nicht in der Datenbank vorhanden sind. Dies bedeutet, dass, wenn Sie einen Link zu einer Modelleigenschaft hinzufügen möchten, Sie auch die Link-Objekte der vorhandenen Modelleigenschaft einschließen sollten, da diese vorhandenen Links sonst gelöscht werden.

Das Beispielprojekt enthält eine Beispieloperation, die dies tut.

Modellversionierung

Die meisten RESPONSUM-Modelle verfügen über eine Versionierung, was bedeutet, dass jede an diesen Modellen vorgenommene Änderung aufgezeichnet wird und diese Versionen eingefroren und genehmigt werden können usw.

Alle Versionen für ein Modell abrufen

Sie können alle Versionsänderungen für ein bestimmtes Modell mit der folgenden GET-Anfrage abrufen: https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]. Dies gibt sowohl „unversionierte“ (Entwurf) als auch jede eingefrorene Version mit zusätzlichen Informationen zu dieser Version zurück, wie z. B. den Versionsstatus, wer die Version erstellt hat, wer sie genehmigt hat usw.

Versionslebenszyklus

Unversionierte Änderungen

Alle Änderungen beginnen als unversionierte Änderungen. Jedes Mal, wenn ein Modell erstellt oder aktualisiert wird, erfassen wir den vorherigen und neuen Wert für die geänderten Eigenschaften. Wer und wann die Änderung vorgenommen hat und welche Art von Operation es war.

Die Liste der Operationen enthält einige gängige Werte wie „create“, „update“, „delete“, „merge“, „import“, „history-restoration“ und „update-link“, kann aber auch spezielle Werte wie „V2-create“ für unseren Legacy-Import enthalten, und jederzeit können je nach zukünftigen Entwicklungen neue Werte hinzugefügt werden.

Einfrieren

Die Änderungen für ein Modell können jederzeit mit POST https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/freeze eingefroren werden, wodurch eine neue Version mit dem Überprüfungsstatus „frozen“ erstellt wird und alle unversionierten Änderungen, die vorhanden waren, eingeschlossen werden. Wenn keine unversionierten Änderungen vorhanden waren, wird keine neue Version erstellt.

Sie können beim Einfrieren auch einen Versionsnamen angeben, aber wenn keiner angegeben wird, wird einer basierend auf den aktuell vorhandenen Versionen berechnet.

Zu diesem Zeitpunkt können bestimmte Personen mit der richtigen Berechtigung diese Version bereits genehmigen oder ablehnen, aber das Wichtigste ist, dass alle neuen Änderungen als unversionierte Änderungen hinzugefügt werden, aber alle Änderungen in dieser Version niemals geändert werden.

Genehmigung anfordern

Um eine Version genehmigen oder ablehnen zu lassen, können Sie bestimmte Personen bitten, sie zu überprüfen. Dazu können Sie PUT https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/request-approval mit einer Versions-UUID & „verantwortlicher Benutzer“-UUID verwenden. Dies löst Benachrichtigungen für diese Person aus, diese Version zu überprüfen und entweder zu genehmigen oder abzulehnen.

Genehmigen oder Ablehnen

Sie können Versionen auch über die API genehmigen oder ablehnen, wenn der mit Ihrem Token verknüpfte Benutzer über ausreichende Berechtigungen verfügt.

Dies kann mit den beiden PUT-Endpunkten https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/approve oder https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/reject erfolgen, wobei wiederum die Versions-UUID erforderlich ist, die Sie genehmigen oder ablehnen möchten.

Webhooks

Manchmal möchten Sie auch über die Erstellung oder Aktualisierung von Modellen benachrichtigt werden. Dafür haben wir Webhooks, die Sie konfigurieren können, indem Sie zu Einstellungen > Integrationen > Webhooks navigieren.

Zur Vereinfachung können Webhooks aktiviert oder deaktiviert werden; nur aktivierte Webhooks lösen Aufrufe aus.

Der Name dient ausschließlich der Unterscheidung der Webhooks.

Die angegebene URL wird mit den angegebenen Headern aufgerufen. Dies ist eine POST-Anfrage, die einen JSON-Body mit changeAction, modelType und UUIDs (ein Array von UUIDs) enthält.

Sie können aus den folgenden Änderungsaktionen wählen; nur für die ausgewählten wird der Webhook aufgerufen:

  • „link-deleted“: wenn ein Link aus einer oder mehreren Eigenschaften entfernt wird
  • „link-created“: wenn ein Link für eine oder mehrere Eigenschaften hinzugefügt wird
  • „item-deleted“: wenn das Element gelöscht wird
  • „item-meta-data-updated“: wenn berechnete Eigenschaften aktualisiert werden, z. B. zuletzt aktualisiert von, Überprüfungsstatus usw.
  • „item-base-data-updated“: wenn die Basiseigenschaften aktualisiert werden, z. B. Name, isObsolete usw.
  • „item-created“: wenn das Element erstellt wird

Sie können das Untermodul auswählen, für das der Webhook ausgelöst werden soll. Dies kann so spezifisch wie ein einzelner Modelltyp oder so breit wie jedes Modell in der Anwendung sein.

Basierend auf unserer internen Logik erhalten Sie möglicherweise mehrere Webhook-Aufrufe für denselben Modelltyp & dieselbe UUID kurz nacheinander, nachdem ein Benutzer gespeichert hat. Das Hinzufügen eines Links und das Festlegen einer Eigenschaft löst beispielsweise einen „item-base-data-updated“-, „item-meta-data-updated“- und „link-created“-Aufruf aus.

Beispielanwendung

https://github.com/RESPONSUM-BE/RESPONSUM-api-example

Lesen Sie die Readme, um loszulegen. Sobald Sie es zum Laufen gebracht und http://localhost:3000 geöffnet haben, sollten Sie so etwas sehen:

Wenn Sie dann die verschiedenen Operationen ausführen, sehen Sie ein Protokoll der Operationen auf der rechten Seite der Seite.

Sie finden all diese Operationen auch im Ordner src\operations\

Was this article helpful?

Related Articles