IT-Assets in der Codenica API

Nachfolgend finden Sie praktische Beispiele für die Arbeit mit den in Codenica gespeicherten IT-Assets. In der Public API lautet der technische Name dieses Objekts assets. Ein einzelnes IT-Asset kann einen Computer, ein Gerät, eine Software, eine Lizenz oder einen anderen in Ihrer Datenbank verfügbaren Inventargegenstand darstellen.

Erstellen Sie vor Ihrer ersten Anfrage den API-Schlüssel aus dem Artikel Codenica API - Einführung. Die folgenden Abschnitte zeigen den vollständigen Ablauf: Schema prüfen und Listen lesen, Datensätze erstellen und bearbeiten, Beziehungen und Dateien verwalten, Batch-Operationen verwenden und Datensätze löschen.

  • einzelne IT-Assets und paginierte Listen lesen;
  • Inventarfelder durchsuchen und filtern;
  • Datensätze erstellen und teilweise aktualisieren;
  • Änderungen mit ETag schützen und Anfragen mit Idempotency-Key sicher wiederholen;
  • IT-Assets mit anderen IT-Assets und Codenica-Objekten verbinden;
  • Dateien hochladen, herunterladen, anhängen und löschen;
  • Statistiken und Feldwerte lesen und mehrere Operationen in einer Anfrage verarbeiten.

Die Beispiele verwenden itemType=computer. Jede Datenbank kann andere Felder enthalten. Lesen Sie vor dem Schreiben das Schema des verwendeten Typs.

IT-Assets - API-Adresse und Bereitstellungsmodell

Senden Sie Anfragen an die öffentliche Adresse, unter der Ihre Codenica-Installation erreichbar ist. Verwenden Sie nicht die Adresse der Datenbank, eines Containers oder eines Ports, der nur innerhalb des Servers erreichbar ist. Die Pfade für IT-Assets beginnen mit:

{BASE_URL}/api/v1/assets

Verwenden Sie bei Codenica Cloud die öffentliche Domain Ihrer Installation:

export BASE_URL="https://ihr-unternehmen.codenica.com"

In der standardmäßigen On-Premise-Installation wird die Adresse lokal durch Codenica Discovery registriert:

export BASE_URL="http://codenica.local:5150"

Wenn der Administrator die On-Premise-Installation über eine Unternehmensdomain, einen Reverse Proxy, HTTPS oder einen anderen externen Port veröffentlicht hat, verwenden Sie die für diese Installation mitgeteilte genaue Adresse:

export BASE_URL="https://api.ihr-unternehmen.example"

Versuchen Sie nicht, die Datenbank über ein zusätzliches Feld im Query-String oder im Body auszuwählen. Die richtige Datenbank wird anhand der Hostadresse ausgewählt. Verwenden Sie localhost nicht, wenn die integrierende Anwendung auf einem anderen Computer als die API läuft. Verwenden Sie in der Produktion HTTPS, wenn die Installation mit einem Zertifikat veröffentlicht ist.

IT-Assets - Scopes des API-Schlüssels

Erstellen Sie den API-Schlüssel in Codenica unter Einstellungen - API - API Keys. Wählen Sie für eine Integration mit IT-Assets nur die benötigten Scopes aus. Der API-Zugriff erweitert weder die Berechtigungen des durch den Schlüssel vertretenen Benutzers noch den in Ihrer Datenbank konfigurierten Datenzugriff.

Grundlegende Scopes für IT-Assets:

  • assets:read - IT-Assets auflisten und lesen;
  • assets:write - IT-Assets erstellen und bearbeiten;
  • assets:delete - IT-Assets löschen;
  • assets:schema - Felder, ihre Eigenschaften und Beziehungsziele lesen;
  • assets:stats - Statistiken und beim Filtern verwendete Feldwerte;
  • assets:relationships:read - Beziehungen lesen;
  • assets:relationships:write - Beziehungen hinzufügen und entfernen;
  • assets:files:read - Dateien auflisten und herunterladen;
  • assets:files:write - Dateien hochladen, anhängen, als Hauptdatei auswählen und löschen;
  • assets:technical:read - als technisch markierte Felder lesen;
  • assets:technical:write - beschreibbare technische Felder schreiben;
  • assets:secrets:write - geheime Felder schreiben, wenn das Schema sie bereitstellt.

Technische und geheime Felder werden für normale Lese- oder Aktualisierungsvorgänge im Inventar nicht benötigt. Geheimnisse werden nur mit dem passenden Scope gespeichert und in Antworten nicht zurückgegeben.

Kopieren Sie nach der Erstellung die Client ID und das Client Secret in den sicheren Speicher der integrierenden Anwendung. Das Secret wird nur bei der Erstellung oder Rotation des Schlüssels angezeigt. Die externe Anwendung verwendet diese beiden Werte, nicht die Panelsitzung und kein Bearer-JWT.

IT-Assets - Authentifizierung und Kontext

Senden Sie jede Anfrage mit den beiden API-Schlüssel-Headern:

export CLIENT_ID="cna_Ihre_client_id"
export CLIENT_SECRET="cns_Ihr_client_secret"

curl --request GET --url "$BASE_URL/api/v1/context" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Lesen Sie vor dem eigentlichen Start der Integration /api/v1/context. Prüfen Sie, ob sich die Antwort auf die richtige Datenbank bezieht, ob caller.authentication den Wert api_key hat und ob die Scopes die benötigten Operationen enthalten.

Bestätigen Sie im Objekt capabilities, dass assets verfügbar ist, und lesen Sie die Limits aus, darunter maxPageSize, maxUploadBytes und das Anfrage-Limit. Bewahren Sie meta.requestId auf. Mit dieser Kennung lässt sich eine bestimmte Anfrage in den Logs oder beim Kontakt mit dem Administrator finden.

Wenn der Kontext auf eine andere Datenbank verweist oder ein erforderlicher Scope fehlt, stoppen Sie die Integration und korrigieren Sie den Schlüssel oder die API-Adresse. Versuchen Sie nicht, die Datenbank über Daten im Body zu wechseln.

IT-Assets - Feld- und Beziehungsschema

Das Schema zeigt, was in der verwendeten Datenbank gelesen und geschrieben werden kann. Rufen Sie es für den benötigten IT-Asset-Typ ab:

curl --request GET --url "$BASE_URL/api/v1/assets/schema?itemType=computer" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Prüfen Sie für jedes Feld mindestens:

  • Name und Datentyp;
  • readable und writable;
  • required;
  • technical und, falls vorhanden, secretWriteOnly;
  • die Werte in options;
  • maximale Länge und Eindeutigkeit;
  • automatische Vergabe und zusätzliche Anforderungen der Datenbank.

Das Schema kann sich je nach itemType und Inventarkonfiguration unterscheiden. Das Feld category kann zum Beispiel in zwei Datenbanken unterschiedliche Werte akzeptieren. Bauen Sie die Integration nicht auf der Annahme auf, dass die Liste der Felder oder Optionen unverändert bleibt.

Das Schema enthält außerdem den Katalog der Beziehungsziele. Prüfen Sie vor dem Senden einer Beziehung, ob der gewählte Objekttyp, sein targetItemType und der Beziehungstyp mit der Antwort übereinstimmen.

IT-Assets - verfügbare Endpunkte

Die folgende Übersicht zeigt die wichtigsten Pfade für eine Integration. Ersetzen Sie {id}, {targetDataSet}, {targetId} und {fileId} durch die richtigen Kennungen.

  • GET /api/v1/assets - Liste der IT-Assets;
  • GET /api/v1/assets/schema - Schema;
  • GET /api/v1/assets/stats - Statistiken;
  • GET /api/v1/assets/values - Feldwerte;
  • GET /api/v1/assets/{id} - einzelnes IT-Asset;
  • POST /api/v1/assets - Erstellen;
  • PATCH /api/v1/assets/{id} - teilweise Aktualisierung;
  • DELETE /api/v1/assets/{id} - Löschen;
  • POST /api/v1/assets:batch - Erstellen, Aktualisieren und Löschen;
  • GET /api/v1/assets/{id}/relationships - Beziehungsliste;
  • POST /api/v1/assets/{id}/relationships - Beziehung hinzufügen;
  • POST /api/v1/assets/{id}/relationships:batch - Beziehungen gesammelt ändern;
  • DELETE /api/v1/assets/{id}/relationships/{targetDataSet}/{targetId} - Beziehung entfernen;
  • GET /api/v1/assets/{id}/files - Dateiliste;
  • POST /api/v1/assets/{id}/files - Datei hochladen;
  • POST /api/v1/assets/{id}/files/{fileId} - vorhandene Datei anhängen;
  • PUT /api/v1/assets/{id}/files/{fileId}/main - Hauptdatei auswählen;
  • DELETE /api/v1/assets/{id}/files/{fileId} - Datei löschen;
  • GET /api/v1/assets/{id}/files/{fileId}/content - Dateiinhalt herunterladen.

Der für einen Pfad benötigte Scope ergibt sich aus der Operation. Wenn Sie 403 erhalten, prüfen Sie zuerst die Scopes des Schlüssels und die Berechtigungen des zugeordneten Benutzers.

IT-Assets - Listen und Paginierung

Lesen Sie die Liste seitenweise. Diese Anfrage gibt die ersten zwanzig sichtbaren IT-Assets vom Typ computer zurück:

curl --request GET --url "$BASE_URL/api/v1/assets?itemType=computer&page=1&pageSize=20" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Eine Collection-Antwort hat beispielsweise diese Struktur:

{
  "data": {
    "items": [
      {
        "id": "11111111-1111-1111-1111-111111111111",
        "itemType": "computer",
        "attributes": {
          "customId": "CND-OFFICE-PC-01",
          "name": "Bürocomputer 01",
          "category": "Hardware"
        },
        "meta": {
          "dateUpdated": "2026-09-07T10:00:00Z",
          "etag": "\"etag-v1\""
        }
      }
    ],
    "page": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false
  },
  "meta": {
    "requestId": "request-id-from-response"
  }
}

Gehen Sie nicht davon aus, dass die erste Seite alle Daten enthält. Lesen Sie weiter, solange hasNextPage den Wert true hat, oder verwenden Sie totalPages. Setzen Sie pageSize nicht höher als das im Kontext zurückgegebene Limit.

IT-Assets - Suche und Filter

Verwenden Sie search für eine einfache Suche. Für eine genauere Auswahl nach Feldern verwenden Sie die Kurzparameter oder den Parameter filter:

curl --request GET --url "$BASE_URL/api/v1/assets?itemType=computer&search=office&page=1&pageSize=50" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

curl --request GET --url "$BASE_URL/api/v1/assets?customId=CND-OFFICE-PC-01" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

curl --request GET --url "$BASE_URL/api/v1/assets?filter=category:contains:Hardware" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Sie können unter anderem itemType, ids, search, name, category, status, location, department, manufacturer, model, serialNumber, inventoryNumber, customId, tag, createdAfter, createdBefore, updatedAfter und updatedBefore verwenden.

Der Parameter filter unterstützt unter anderem diese Operatoren:

  • eq - gleich;
  • ne - ungleich;
  • in - einer der angegebenen Werte;
  • contains - enthält einen Teil;
  • startsWith und endsWith - beginnt oder endet mit dem angegebenen Text;
  • empty und notEmpty - leeres oder nicht leeres Feld;
  • gt, gte, lt, lte - Vergleiche.
filter=status:eq:In service
filter=serialNumber:contains:ABC
filter=category:in:Hardware,Software
filter=description:notEmpty:

Wenn ein Wert Leerzeichen oder Sonderzeichen enthält, kodieren Sie ihn nach den URL-Regeln. Denken Sie beim Filtern nach Kennungen daran, dass ids das Ergebnis auf die angegebenen UUIDs beschränkt.

IT-Assets - Felder auswählen und Daten einbinden

Der Parameter fields begrenzt die in der Antwort zurückgegebenen Felder. Das ist hilfreich, wenn die Integration nur wenige Werte benötigt:

curl --request GET --url "$BASE_URL/api/v1/assets?fields=id,itemType,name,category,status" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Verwenden Sie include, um verbundene Daten zu lesen. Für IT-Assets sind files und relationships verfügbar:

curl --request GET --url "$BASE_URL/api/v1/assets/$ASSET_ID?include=files,relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Scopes für eingebundene Daten müssen durch den Schlüssel erlaubt sein. Wenn der Schlüssel assets:files:read oder assets:relationships:read nicht besitzt, lesen Sie den Datensatz ohne die entsprechende Einbindung oder erweitern Sie den Schlüssel nach dem Prinzip der geringsten Rechte.

fields=* gibt keine geheimen Felder frei. Betrachten Sie die Feldauswahl nicht als Möglichkeit, Berechtigungen zu umgehen. Technische und geheime Felder erscheinen nur, wenn Scopes und Schema dies erlauben.

IT-Assets - einen Datensatz erstellen

Verwenden Sie POST /api/v1/assets, um einen Datensatz zu erstellen. Senden Sie den technischen Typ itemType und die beschreibbaren Felder im Objekt attributes. Dieses Beispiel erstellt einen Bürocomputer:

export IDEMPOTENCY_KEY="asset-create-20260907-0001"

curl --request POST --url "$BASE_URL/api/v1/assets" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-raw '{
    "itemType": "computer",
    "attributes": {
      "customId": "CND-OFFICE-PC-01",
      "name": "Bürocomputer 01",
      "category": "Hardware",
      "manufacturer": "Lenovo",
      "model": "ThinkCentre",
      "location": "Berlin",
      "status": "In service"
    }
  }'

Im Basismodell sind mindestens name und category erforderlich. Ihre Datenbank kann jedoch zusätzliche Anforderungen, Auswahlwerte oder Regeln für eindeutige Werte enthalten. Vergleichen Sie den Body immer mit dem aktuellen Schema.

Eine erfolgreiche Antwort hat den Status 201 Created. Speichern Sie data.id, data.meta.etag und den HTTP-Header ETag. Ein Beispielausschnitt:

{
  "data": {
    "id": "11111111-1111-1111-1111-111111111111",
    "itemType": "computer",
    "attributes": {
      "customId": "CND-OFFICE-PC-01",
      "name": "Bürocomputer 01",
      "category": "Hardware"
    },
    "meta": {
      "customId": "CND-OFFICE-PC-01",
      "dateCreated": "2026-09-07T10:00:00Z",
      "dateUpdated": "2026-09-07T10:00:00Z",
      "etag": "\"etag-v1\""
    }
  },
  "meta": {
    "requestId": "request-id-from-response",
    "etag": "\"etag-v1\""
  }
}

Senden Sie keine eigene id, außer wenn das Schema und die Integration eine kontrollierte UUID verlangen. Wenn Sie eine eigene Kennung verwenden, muss sie noch nicht vergeben sein und die Anforderungen der API erfüllen.

IT-Assets - eine Erstellung sicher wiederholen

Nach einem Timeout wissen Sie möglicherweise nicht, ob der Server den Datensatz erstellt hat. Erzeugen Sie nicht sofort einen neuen Idempotenzschlüssel. Senden Sie exakt dieselbe Anfrage mit demselben Idempotency-Key und einem identischen Body:

curl --request POST --url "$BASE_URL/api/v1/assets" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-raw '{
    "itemType": "computer",
    "attributes": {
      "customId": "CND-OFFICE-PC-01",
      "name": "Bürocomputer 01",
      "category": "Hardware",
      "manufacturer": "Lenovo",
      "model": "ThinkCentre",
      "location": "Berlin",
      "status": "In service"
    }
  }'

Das erneute Senden derselben Operation gibt die erste Antwort wieder aus und erstellt keinen zweiten Datensatz. Derselbe Schlüssel darf später keinen anderen Body, Endpoint oder Vorgang beschreiben. Eine solche Wiederverwendung führt zu 422 idempotency_key_reused.

Idempotenz gilt auch für andere schreibende Anfragen: Aktualisierungen, Beziehungsänderungen, Dateioperationen und Löschvorgänge. Verwenden Sie für jeden neuen Vorgang einen neuen Wert.

IT-Assets - einen Datensatz lesen

Lesen Sie ein erstelltes oder gefundenes IT-Asset über seine UUID:

export ASSET_ID="11111111-1111-1111-1111-111111111111"

curl --request GET --url "$BASE_URL/api/v1/assets/$ASSET_ID?include=files,relationships" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Antwort enthält id, den technischen Wert itemType, die Felder in attributes und Metadaten in meta. Das ETag finden Sie im HTTP-Header und normalerweise auch in data.meta.etag sowie in der Hülle meta.etag.

Lesen Sie das IT-Asset vor jeder Änderung erneut. Das gilt für Feldänderungen, Beziehungen, Uploads, die Auswahl der Hauptdatei, das Löschen einer Datei und das Löschen des gesamten Datensatzes. So arbeitet der Vorgang mit der aktuellen Version und nicht mit einem veralteten Wert aus dem Speicher der Integration.

IT-Assets - teilweise Aktualisierung mit ETag

PATCH ändert nur die im Body enthaltenen Felder. Sie müssen nicht den vollständigen Datensatz senden. Fügen Sie ein aktuelles ETag aus dem letzten Lesevorgang und einen neuen Idempotenzschlüssel hinzu:

export ASSET_ETAG='"etag-v1"'
export IDEMPOTENCY_KEY="asset-update-20260907-0001"

curl --request PATCH --url "$BASE_URL/api/v1/assets/$ASSET_ID" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "If-Match: $ASSET_ETAG" \
  --data-raw '{
    "attributes": {
      "name": "Bürocomputer 01 - aktualisiert",
      "description": "IT-Asset durch die Integration aktualisiert."
    }
  }'

Nach dem Erfolg hat die Antwort den Status 200 OK und enthält ein neues ETag. Ersetzen Sie den bisherigen Wert vor dem nächsten Vorgang. Das Senden von null leert ein Feld, sofern es nicht erforderlich ist und das Schema einen leeren Wert zulässt.

Der Body muss eine tatsächliche Änderung an einem beschreibbaren Feld, einem benutzerdefinierten Wert oder einer Beziehung enthalten. Ein schreibgeschütztes, technisches oder geheimes Feld kann einen eigenen Scope oder Endpoint benötigen.

IT-Assets - Schutz vor einer veralteten Version

ETag verhindert, dass ein Datensatz durch eine zwischenzeitliche Änderung einer anderen Person oder Integration überschrieben wird. Zwei Situationen müssen getrennt behandelt werden:

  • 428 if_match_required - der erforderliche If-Match-Header oder bei einer Änderung der Idempotency-Key fehlt;
  • 412 if_match_failed - das übermittelte ETag ist nicht mehr aktuell.

Beispiel für die Antwort bei einem veralteten ETag:

{
  "type": "https://docs.codenica.com/errors/if_match_failed",
  "title": "Precondition failed.",
  "status": 412,
  "detail": "The supplied ETag is not the current asset version.",
  "instance": "/api/v1/assets/11111111-1111-1111-1111-111111111111",
  "code": "if_match_failed",
  "requestId": "request-id-from-response"
}

Nach 412 lesen Sie das IT-Asset erneut, vergleichen Sie die aktuellen Werte mit Ihrer geplanten Änderung und senden Sie erst danach ein neues PATCH mit dem neuen ETag. Wiederholen Sie nicht endlos dieselbe Anfrage mit einem veralteten ETag. Ein konkreter If-Match-Wert ist die empfohlene Vorgehensweise für Integrationen. Der Wert * gehört zu einem kontrollierten Szenario und sollte bei einer normalen Synchronisierung nicht die Versionsprüfung ersetzen.

IT-Assets - Beziehungen hinzufügen

Eine Beziehung verbindet ein IT-Asset mit einem anderen sichtbaren Objekt. Zu den verfügbaren Zielen gehören:

assets, clients, documents, tickets, changes, problems, releases,
notes, worktasks, confirmations, requesteditems

Dieses Beispiel verbindet zwei Computer. Wenn Sie targetItemType senden, muss der Wert dem tatsächlichen Typ des Ziels entsprechen:

export TARGET_ASSET_ID="22222222-2222-2222-2222-222222222222"
export IDEMPOTENCY_KEY="asset-relation-add-20260907-0001"

curl --request POST --url "$BASE_URL/api/v1/assets/$ASSET_ID/relationships" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "If-Match: $ASSET_ETAG" \
  --data-raw '{
    "targetId": "22222222-2222-2222-2222-222222222222",
    "targetDataSet": "assets",
    "targetItemType": "computer",
    "relationshipType": "related"
  }'

Das Ziel muss vorhanden und für den dem Schlüssel zugeordneten Benutzer sichtbar sein. Ein IT-Asset darf nicht auf sich selbst zeigen. Je nach Ziel kann die API relationshipType speichern. Senden Sie dieses Feld für notes, worktasks und requesteditems nicht, weil das aktuelle Beziehungsmodell es nicht speichert.

Das Hinzufügen einer Beziehung ändert die Version des Quell-Assets. Lesen Sie die Quelle nach der Antwort 201 Created erneut und verwenden Sie das neue ETag für die nächste Änderung.

IT-Assets - Beziehungen lesen und entfernen

Lesen Sie Beziehungen über die Collection und begrenzen Sie das Ergebnis bei Bedarf auf ein bestimmtes Zieldataset:

curl --request GET --url "$BASE_URL/api/v1/assets/$ASSET_ID/relationships?targetDataSet=assets&page=1&pageSize=50" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Ein Beziehungselement kann unter anderem targetId, targetDataSet, targetItemType, relationshipType, customId und name enthalten. Beim Lesen einer Beziehung erhalten Sie nicht das vollständige Zielobjekt, außer Sie lesen es separat oder verwenden include=relationships.

Zum Entfernen einer Beziehung benötigen Sie ein aktuelles ETag der Quelle:

export IDEMPOTENCY_KEY="asset-relation-delete-20260907-0001"

curl --request DELETE --url "$BASE_URL/api/v1/assets/$ASSET_ID/relationships/assets/$TARGET_ASSET_ID?relationshipType=related" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "If-Match: $ASSET_ETAG"

Eine erfolgreiche Entfernung gibt 200 OK mit data: true zurück. Beim direkten Endpoint muss der Wert von relationshipType in der Query der zu entfernenden Beziehung entsprechen. Lesen Sie nach dem Vorgang die Collection und das Quell-Asset erneut.

IT-Assets - mehrere Beziehungen gesammelt ändern

Verwenden Sie relationships:batch, wenn Sie mehrere Beziehungen hinzufügen oder entfernen müssen. Eine Anfrage kann die Arrays add und remove enthalten:

export IDEMPOTENCY_KEY="asset-relations-batch-20260907-0001"

curl --request POST --url "$BASE_URL/api/v1/assets/$ASSET_ID/relationships:batch" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "If-Match: $ASSET_ETAG" \
  --data-raw '{
    "add": [
      {
        "targetId": "22222222-2222-2222-2222-222222222222",
        "targetDataSet": "assets",
        "targetItemType": "computer",
        "relationshipType": "related"
      }
    ],
    "remove": [
      {
        "targetId": "33333333-3333-3333-3333-333333333333",
        "targetDataSet": "clients",
        "relationshipType": "owner"
      }
    ]
  }'

Die Antwort 200 OK enthält die Zähler added, removed und skipped. Das erneute Senden einer bereits vorhandenen Beziehung kann als skipped gezählt werden. Ein Beziehungs-Batch ändert ebenfalls das ETag der Quelle. Lesen Sie das IT-Asset daher danach erneut.

Lassen Sie bei Elementen für notes, worktasks und requesteditems das Feld relationshipType weg. Jedes Ziel muss sichtbar sein und zum Beziehungskatalog aus dem Schema passen.

IT-Assets - Dateien auflisten und hochladen

Dateien werden zusammen mit dem IT-Asset gespeichert und haben eigene Kennungen. Sie können zunächst die aktuelle Liste lesen:

curl --request GET --url "$BASE_URL/api/v1/assets/$ASSET_ID/files?page=1&pageSize=50" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Ein Listenelement enthält unter anderem id, name, fileName, contentType, size, relationshipType, isMain und downloadUrl.

Der Upload verwendet multipart/form-data. Für die Änderung des IT-Assets benötigen Sie ein aktuelles ETag und einen neuen Idempotenzschlüssel:

curl --request POST --url "$BASE_URL/api/v1/assets/$ASSET_ID/files?makeMain=true&relationshipType=documentation" \
  --header "Accept: application/json, application/problem+json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: asset-file-upload-20260907-0001" \
  --header "If-Match: $ASSET_ETAG" \
  --form "file=@./asset-manual.txt;type=text/plain"

makeMain=true wählt die hochgeladene Datei als Hauptdatei aus. Der Parameter relationshipType beschreibt den Zweck der Datei, zum Beispiel documentation oder manual. Das Standardlimit für Uploads beträgt 20 MiB. Prüfen Sie dennoch den aktuellen Wert von maxUploadBytes im Kontext.

Der Dateiname darf keinen Pfad und kein ..-Segment enthalten. Speichern Sie keine Geheimnisse im Dateinamen, in den Metadaten oder im Inhalt, sofern dies nicht notwendig ist.

Der Upload liefert 201 Created und ein Dateiobjekt zurück. Lesen Sie das IT-Asset danach erneut, weil sich sein ETag geändert hat.

IT-Assets - Dateien herunterladen und die Hauptdatei auswählen

Laden Sie den Dateiinhalt über den Endpoint /content herunter. Die Antwort enthält Binärdaten und keine JSON-Hülle:

export FILE_ID="44444444-4444-4444-4444-444444444444"

curl --request GET --url "$BASE_URL/api/v1/assets/$ASSET_ID/files/$FILE_ID/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output ./asset-file-download.txt

downloadUrl im Dateiobjekt ist eine relative Adresse. Ergänzen Sie den Host der Bereitstellung und verwenden Sie dieselben Authentifizierungsheader.

Wenn ein IT-Asset mehrere Dateien besitzt, können Sie eine Hauptdatei auswählen. Dieser Vorgang ändert das Asset und benötigt sein aktuelles ETag:

curl --request PUT --url "$BASE_URL/api/v1/assets/$ASSET_ID/files/$FILE_ID/main" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: asset-set-main-20260907-0001" \
  --header "If-Match: $ASSET_ETAG"

Eine erfolgreiche Antwort hat den Status 200 OK und gibt normalerweise data: true zurück. Lesen Sie die Dateiliste nach der Änderung und prüfen Sie, dass das ausgewählte Element isMain=true und die vorherige Hauptdatei isMain=false hat. Lesen Sie anschließend das neue ETag des IT-Assets.

Eine kleine Datei kann in der Oberfläche auf 0 MB gerundet werden. Prüfen Sie die tatsächliche Größe im Feld size oder anhand der Zahl der heruntergeladenen Bytes.

IT-Assets - eine vorhandene Datei anhängen

Wenn eine Datei bereits im System gespeichert ist, können Sie sie an ein anderes IT-Asset anhängen, ohne den Inhalt erneut hochzuladen:

export TARGET_ASSET_ID="55555555-5555-5555-5555-555555555555"
export TARGET_ASSET_ETAG='"target-etag-v1"'

curl --request POST --url "$BASE_URL/api/v1/assets/$TARGET_ASSET_ID/files/$FILE_ID?makeMain=true&relationshipType=manual" \
  --header "Accept: application/json, application/problem+json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: asset-attach-file-20260907-0001" \
  --header "If-Match: $TARGET_ASSET_ETAG"

Eine Antwort 201 Created enthält die Kennung der angehängten Datei und ihre Metadaten. Wenn Sie makeMain=true verwendet haben, lesen Sie die Liste erneut und prüfen Sie, ob isMain den Wert true hat.

Das Anhängen ändert ebenfalls die Version des Ziel-Assets. Lesen Sie vor der nächsten Dateioperation das aktuelle ETag des Ziels. Löschen Sie eine Datei aus einem IT-Asset erst, wenn Sie geprüft haben, dass sie dort und in ihren anderen Beziehungen nicht mehr benötigt wird.

IT-Assets - eine Datei löschen

Das Löschen einer Datei ändert das IT-Asset. Lesen Sie das aktuelle ETag und verwenden Sie einen eigenen Idempotenzschlüssel:

curl --request DELETE --url "$BASE_URL/api/v1/assets/$ASSET_ID/files/$FILE_ID" \
  --header "Accept: application/json, application/problem+json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: asset-file-delete-20260907-0001" \
  --header "If-Match: $ASSET_ETAG"

Eine erfolgreiche Antwort hat den Status 200 OK und enthält data: true. Lesen Sie nach jedem Löschvorgang die Dateiliste und das ETag des IT-Assets erneut. Wenn Sie mehrere Dateien löschen, muss das ETag für den nächsten Vorgang aus der vorherigen abgeschlossenen Änderung stammen.

Das Löschen einer Datei löscht nicht das gesamte IT-Asset. Der Versuch, den gelöschten Inhalt herunterzuladen, gibt 404 file_not_found zurück. Wenn eine Datei an mehrere IT-Assets angehängt ist, prüfen Sie vor dem Löschen, ob die richtige Beziehung betroffen ist und die Datei nicht mehr benötigt wird.

IT-Assets - Statistiken und Feldwerte

Der Endpoint stats hilft beim Erstellen einer Zusammenfassung sichtbarer Daten. Sie können das Ergebnis auf einen Asset-Typ begrenzen und das Feld angeben, dessen Werte Sie benötigen:

curl --request GET --url "$BASE_URL/api/v1/assets/stats?itemType=computer&field=category&limit=20" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Antwort kann die Gesamtzahl sichtbarer IT-Assets, eine Aufteilung nach itemType, den Feldnamen und die Werte enthalten:

{
  "data": {
    "total": 11,
    "byItemType": {
      "computer": 11
    },
    "field": "category",
    "values": [
      "Laptop",
      "Desktop",
      "Hardware"
    ]
  },
  "meta": {
    "requestId": "request-id-from-response"
  }
}

Der Endpoint values gibt Werte zurück, die sich für Filterlisten eignen:

curl --request GET --url "$BASE_URL/api/v1/assets/values?field=category&itemType=computer&search=hard&limit=20" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Bei der Suche nach hard kann das Ergebnis Hardware enthalten. Beide Endpoints sind schreibgeschützt, benötigen assets:stats und kein ETag. Die Ergebnisse enthalten nur für den Benutzer sichtbare Daten.

IT-Assets - Batch-Operationen

Batch verbindet Erstellen, Aktualisieren und Löschen in einer Anfrage. Jedes Element hat eine eigene Operation, und update sowie delete übergeben ihr ETag im Feld ifMatch:

curl --request POST --url "$BASE_URL/api/v1/assets:batch" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: assets-batch-20260907-0001" \
  --data-raw '{
    "items": [
      {
        "operation": "create",
        "create": {
          "itemType": "computer",
          "attributes": {
            "customId": "CND-BATCH-PC-01",
            "name": "Computer im Batch erstellt",
            "category": "Hardware"
          }
        }
      },
      {
        "operation": "update",
        "id": "11111111-1111-1111-1111-111111111111",
        "ifMatch": "\"current-etag\"",
        "update": {
          "attributes": {
            "description": "Beschreibung im Batch aktualisiert."
          }
        }
      },
      {
        "operation": "delete",
        "id": "22222222-2222-2222-2222-222222222222",
        "ifMatch": "\"current-etag\""
      }
    ]
  }'

Wenn alle Elemente erfolgreich sind, hat die Antwort den Status 200 OK. Das Ergebnis enthält succeeded, failed und das Ergebnis jedes Elements mit index, operation und status.

Batch ist keine Alles-oder-nichts-Transaktion. Bei einem Teilerfolg gibt die API 207 Multi-Status zurück. Erfolgreiche Elemente werden nicht zurückgerollt. Prüfen Sie jedes Element. Wenn der Batch neue Datensätze erstellt, speichern Sie deren IDs und ETags aus den einzelnen Ergebnissen.

Jedes Element benötigt den Scope für seine Operation. Eine Batch-Anfrage erweitert die Berechtigungen des Schlüssels nicht.

IT-Assets - einen Datensatz löschen

Lesen Sie das IT-Asset vor dem Löschen erneut und verwenden Sie sein aktuelles ETag:

export IDEMPOTENCY_KEY="asset-delete-20260907-0001"

curl --request DELETE --url "$BASE_URL/api/v1/assets/$ASSET_ID" \
  --header "Accept: application/json, application/problem+json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "If-Match: $ASSET_ETAG"

Eine erfolgreiche Löschung gibt 200 OK mit data: true zurück. Ein späterer Aufruf mit der UUID liefert 404 asset_not_found. Die Löschung führt die vorhandene fachliche Bereinigung aus. Die Public API löscht jedoch verbundene Geschäftsobjekte wie Dokumente, Tickets oder Kunden nicht automatisch.

Entfernen Sie die Kennung nach dem Löschen aus dem lokalen Index der Integration oder markieren Sie den Datensatz als inaktiv. Versuchen Sie nicht, die gelöschte UUID erneut zu aktualisieren.

IT-Assets - Fehler, Limits und Sicherheit

API-Fehler verwenden das Problem-Details-Format mit zusätzlichen Codenica-Feldern:

{
  "type": "https://docs.codenica.com/errors/asset_not_found",
  "title": "Asset not found.",
  "status": 404,
  "detail": "The asset does not exist or is outside the caller's access scope.",
  "instance": "/api/v1/assets/11111111-1111-1111-1111-111111111111",
  "code": "asset_not_found",
  "requestId": "request-id-from-response"
}

Verwenden Sie in der Anwendungslogik vor allem status und code. Der Text in detail ist ein Hinweis für Menschen und kann sich ändern.

  • 400 - ungültiger Body, Parameter oder Feldwert;
  • 401 - fehlende oder ungültige Authentifizierung;
  • 403 - fehlender Scope oder fehlende Benutzerberechtigung;
  • 404 - IT-Asset, Datei oder Beziehungsziel nicht vorhanden oder nicht sichtbar;
  • 409 - Konflikt bei Daten oder fachlichem Status;
  • 412 - veraltetes ETag;
  • 413 - Upload oder Body zu groß;
  • 428 - ETag oder Idempotency-Key erforderlich;
  • 429 - Anfrage-Limit überschritten;
  • 500 oder 503 - Serverfehler oder vorübergehende Nichtverfügbarkeit.

Lesen Sie X-RateLimit-Limit, X-RateLimit-Remaining und bei 429 Retry-After. Verwenden Sie kontrollierte Wiederholungen mit steigenden Wartezeiten. Speichern Sie das Client Secret niemals in einem Repository, einer URL, an den Browser ausgeliefertem Code, der Befehls-Historie oder Logs.

IT-Assets - vollständiger Integrationsablauf

  1. Ermitteln Sie die richtige API-Adresse. Prüfen Sie bei On-Premise, ob die Integration http://codenica.local:5150 oder die vom Administrator veröffentlichte Adresse erreichen kann.
  2. Erstellen Sie einen eigenen API-Schlüssel für diese Integration und wählen Sie die minimal erforderlichen Scopes.
  3. Speichern Sie Client ID und Client Secret in einem sicheren Speicher.
  4. Senden Sie GET /api/v1/context und prüfen Sie, ob die Antwort die richtige Datenbank betrifft. Prüfen Sie außerdem Caller, Scopes und Limits.
  5. Senden Sie GET /api/v1/assets/schema?itemType=computer und passen Sie den Body an die aktuellen Felder an.
  6. Lesen Sie die Liste mit Paginierung, Suche oder Filtern.
  7. Erstellen Sie ein IT-Asset mit POST und einem neuen Idempotency-Key.
  8. Speichern Sie UUID und ETag.
  9. Lesen Sie den aktuellen Datensatz vor jeder Änderung erneut.
  10. Führen Sie Aktualisierungen, Beziehungen, Dateioperationen und Löschvorgänge mit einem konkreten ETag und einem neuen Idempotenzschlüssel aus.
  11. Speichern Sie nach jeder erfolgreichen Änderung das neue ETag und lesen Sie das Ergebnis bei Bedarf erneut.
  12. Lesen Sie den Datensatz nach 412 erneut, lösen Sie den Konflikt und wiederholen Sie den Vorgang erst danach.
  13. Verwenden Sie Batch für größere Mengen, prüfen Sie aber jedes Element, weil Batch keine Transaktion ist.
  14. Behandeln Sie 429 und protokollieren Sie keine Geheimnisse.
  15. Löschen Sie den API-Schlüssel, wenn die Integration nicht mehr verwendet wird.

Mit diesem Ablauf kann die Integration Inventardaten nutzen, ohne von der internen Struktur der Datenbank abhängig zu sein. Wenn sich Feldkonfiguration, Berechtigungen oder Bereitstellungsadresse ändern, lesen Sie Kontext und Schema erneut, statt sich auf frühere Annahmen zu verlassen.