Integration eines externen Quellsystems über die Public REST API (Beispiel-Anwendungsfall)

Die Integration verbindet ein externes Quellsystem mit der Public REST API, um asset-bezogene Stammdaten zu synchronisieren.

Der grundlegende Datenfluss ist:

Externes Quellsystem des Kunden

→ Integrationskomponente / Middleware des Kunden

→ caralegal Public REST API

Das externe Quellsystem bleibt das führende System für die synchronisierten Stammdaten. caralegal empfängt diese Informationen als Assets und verwendet sie in Datenschutz-, Compliance- und Governance-Prozessen.

Weitere Quellsysteme können später angebunden werden, sind jedoch nicht Teil des initialen Integrationsumfangs.

Die Public REST API stellt Endpunkte zum Lesen, Erstellen und Aktualisieren von Assets und Referenzdaten bereit.

Link zur Public REST API OpenAPI-Dokumentation: https://public-api.caralegal.de/swagger/#/

Zugangsdaten (Login und Passwort) für die Dokumentation erhalten Sie von Ihrem caralegal CS / Tech-Support.

Die Implementierung der Synchronisationslogik oder Middleware liegt außerhalb des Verantwortungsbereichs von caralegal. Der Integrationsverantwortliche oder Implementierungspartner ist zuständig für:

Jedes aus dem Quellsystem importierte Objekt sollte den stabilen Quellsystem-Bezeichner als externalId speichern.

Beispiel:

{

"name": "SAP HCM",

"externalId": "source-12345"

}

Die externalId dient als eindeutige technische Referenz zwischen dem Quellsystem und caralegal.

Empfohlene Vorgehensweise:

So werden Duplikate vermieden und bestehende Verknüpfungen in caralegal bleiben erhalten. Bestehende Assets sollten grundsätzlich aktualisiert und nicht gelöscht und neu angelegt werden.

Die externalId kann direkt in REST-API-Aufrufen verwendet werden, indem das Präfix ext:: vorangestellt wird.

Beispiele:

GET /api/assets/ext::source-12345

PATCH /api/assets/ext::source-12345

DELETE /api/assets/ext::source-12345

Die Integration muss daher keine internen System-IDs speichern.

Empfohlene Vorgehensweise:

Dasselbe Prinzip gilt für andere Objekttypen, die externalId unterstützen, wie z. B.:

Die Public REST API unterstützt Teilaktualisierungen über PATCH.

Es müssen nur die Felder übermittelt werden, die geändert werden sollen.

Beispiel:

{

"name": "SAP HCM Cloud",

"lastSyncedAt": "2026-08-19T10:00:00.000Z"

}

Alle nicht im Request enthaltenen Attribute bleiben unverändert.

So können Stammdaten aus dem Quellsystem synchronisiert werden, während datenschutz- oder compliance-spezifische Informationen weiterhin direkt in caralegal gepflegt werden.

Beispiel für ein Eigentümerschaftsmodell:

Quellsystem pflegt:

caralegal pflegt:

Für jedes synchronisierte Feld sollte klar definiert sein, welches System führend ist.

Wird beispielsweise der Asset-Name aus dem Quellsystem synchronisiert, kann eine manuelle Änderung dieses Namens in caralegal beim nächsten Synchronisationslauf überschrieben werden.

Felder, die ausschließlich in caralegal gepflegt werden, sind davon nicht betroffen, da sie durch die Middleware nicht aktualisiert werden.

Jede erfolgreiche Anlage- oder Aktualisierungsoperation kann enthalten lastSyncedAt.

Beispiel:

{

"lastSyncedAt": "2026-08-19T10:00:00.000Z"

}

Dieses Feld dokumentiert den Zeitstempel der letzten erfolgreichen Synchronisation und unterstützt:

Die Delta-Erkennung und Zeitstempelverwaltung erfolgen durch die Integrationskomponente.

Assets können kategorisiert werden über labelIds.

Beispiele für Labels:

Labels unterstützen Klassifizierung, Filterung und Nachvollziehbarkeit. Die technische Asset-Identifikation sollte weiterhin über externalId erfolgen. externalId.

{

"name": "SAP HCM",

"status": "ACTIVE",

"externalId": "source-12345",

"lastSyncedAt": "2026-08-19T10:00:00.000Z",

"resourceAssetTypeId": "...",

"assetOwnerId": "...",

"riskOwnerId": "...",

"mainOrgUnitId": "...",

"orgUnitIds": ["..."],

"labelIds": ["..."],

"dataLocationIds": ["..."],

"externalRecipientIds": ["..."]

}

Nicht alle Felder müssen in der initialen Integrationsphase verwendet werden. Das konkrete Mapping hängt von den im Quellsystem verfügbaren Informationen und dem geplanten Integrationsumfang ab.

Assets:

/api/assets

Benutzer:

/api/users

Verwendet für:

Organisationseinheiten:

/api/org-units

Verwendet für:

Labels:

/api/Ressourcen/label

Asset-Typen:

/api/Ressourcen/asset-type

Datenstandorte:

/api/data-locations

Externe Empfänger:

/api/external-recipients

Weitere Referenzdaten sind allgemein verfügbar über:

/api/Ressourcen

/api/Ressourcen/{resourceType}

Risiken und Maßnahmen sind je nach aktuellem API-Umfang nicht über die Public API verfügbar.

Für technische Integrationen kann ein Refresh Token bereitgestellt und als Bearer Token für API-Aufrufe verwendet werden.

Beispiel:

Authorization: Bearer <refresh-token>

Content-Type: application/json

Accept: application/json

Das Refresh Token ist für die langfristige Nutzung innerhalb der Integration vorgesehen und sollte sicher gespeichert werden, z. B. in einem Secret-Management-System.

Alternativ kann ein Access-Token-Flow verwendet werden, wenn dies besser zur Integrationsarchitektur passt. In diesem Fall wird auf Basis des Refresh Tokens und der Client Credentials ein Access Token generiert und für API-Aufrufe verwendet.

Neue Assets werden über die API angelegt.

Nach einer erfolgreichen Anlage kann die neu erstellte interne Ressourcen-ID im HTTP-Header x-resource-id zurückgegeben werden.

Die Integration muss diese interne ID jedoch nicht dauerhaft speichern. Der empfohlene Ansatz ist, den Quellsystem-Bezeichner als externalId zu verwenden.

Bestehende Assets werden über PATCH aktualisiert. Da Teilaktualisierungen unterstützt werden, müssen nur die Felder übermittelt werden, die tatsächlich geändert werden sollen. Bestehende Verknüpfungen und nicht enthaltene Attribute bleiben unverändert.

Viele GET-Endpunkte unterstützen cursor-basiertes Paging.

Beispiel:

GET /api/assets?limit=100

Typische Antwort:

{

"items": [],

"cursors": {

"current": null,

"next": "..."

}

}

Ist cursors.next vorhanden, wird die nächste Seite wie folgt abgerufen:

GET /api/assets?limit=100&cursor=<next>

Dieser Vorgang wird wiederholt, bis kein weiterer Cursor mehr zurückgegeben wird.

Bei einigen Endpunkten kann der Name der Ergebnisliste abweichen, z. B users statt items.

Die Integration nutzt ein externes Quellsystem als führendes System für ausgewählte Asset-Stammdaten.

Die Public REST API unterstützt:

Synchronisationslogik, Mapping, Betrieb, Monitoring und Fehlerbehandlung werden durch den Integrationsverantwortlichen oder Implementierungspartner umgesetzt.

This approach keeps the integration lightweight, avoids the need to persist internal target-system IDs, and preserves existing privacy and Compliance-Verknüpfungen when asset master data is updated.