Releases in der Codenica API

Beginnen Sie die Arbeit mit Releases über die Codenica API, indem Sie in den Codenica-Einstellungen einen Schlüssel erstellen. Wenn noch kein Schlüssel vorhanden ist, öffnen Sie Codenica API - Einführung in einem neuen Tab. Dort finden Sie die gemeinsamen Regeln für die Ausstellung von Schlüsseln, die Speicherung des Secrets und die Authentifizierung.

Der technische Modulname lautet releases, der Typ eines einzelnen Objekts lautet release. Ein Release beschreibt die geplante Veröffentlichung oder Bereitstellung von Änderungen in einer IT-Umgebung. Zusätzlich zu den beschreibenden Daten besitzt es eigene Felder für Build, Tests, Testergebnisse und die Bereitstellungsplanung.

Die folgenden Abschnitte behandeln die Adresse, Scopes, das Schema, Listen, Filter, Erstellung, Änderungen, ETags, Batch-Operationen, Beziehungen, Benutzer, Dateien, Workflow-Aktionen, Genehmigungen und das Löschen von Releases.

Die Beispiele verwenden die Kennung PUBLIC-API-RELEASE-20260905133117. Ersetzen Sie sie durch Ihre eigene Kennung und passen Sie E-Mail-Adressen, IDs und Feldwerte an die Daten in Ihrer Datenbank an.

Releases - API-Adresse und Installationsauswahl

Alle Release-Routen beginnen mit:

{BASE_URL}/api/v1/releases

Verwenden Sie bei Codenica Cloud die öffentliche Adresse, die der betreffenden Datenbank zugewiesen ist:

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

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

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

Wenn der Administrator die Installation unter einer Unternehmensdomain, über einen Reverse Proxy, mit HTTPS oder an einem anderen Port veröffentlicht hat, verwenden Sie die genaue Adresse, die für diese Installation angegeben wurde:

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

Verwenden Sie localhost nicht, wenn das Integrationsprogramm auf einem anderen Computer als die API läuft. Senden Sie tenantId weder im Body noch in der Query-String. Die richtige Datenbank wird anhand der von der Integration verwendeten Adresse ausgewählt.

Releases - API-Schlüssel und Lizenzlimits

Erstellen Sie einen API-Schlüssel in Codenica unter Einstellungen - API - API Keys. Das Secret wird nur einmal direkt nach der Erstellung oder Rotation des Schlüssels angezeigt. Speichern Sie dann die Client ID und das Client Secret im sicheren Speicher der Integration.

Die Codenica API ist mit den Lizenzen Plus und Enterprise verfügbar. Plus erlaubt bis zu 50 aktive Schlüssel, Enterprise bis zu 100. Starter stellt die Codenica API nicht bereit. Erstellen Sie für jede Anwendung und jede Umgebung einen eigenen Schlüssel, damit Scopes, Secret-Rotation und Zugriff unabhängig verwaltet werden können.

Abgelaufene oder inaktive Schlüssel bleiben sichtbar, bis Sie Löschen verwenden, belegen aber keinen aktiven Platz im Limit. Das Löschen eines Schlüssels ist dauerhaft. Wenn Sie kein Enddatum festlegen, beträgt die standardmäßige Aktivitätsdauer 90 Tage. Die maximale Aktivitätsdauer eines Schlüssels beträgt 5 Jahre.

Releases - Authentifizierung und sichere Anfragen

Authentifizieren Sie jede Anfrage an die Codenica API mit den beiden 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/releases?page=1&pageSize=25" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Eine externe Integration benötigt weder das JWT des Administrators noch Cookies aus dem Codenica-Panel. Legen Sie den Schlüssel nicht in einem Repository, in an den Browser ausgeliefertem Code, in einer URL, in der Befehlszeile oder in Logs ab. Verwenden Sie außerhalb lokaler Tests HTTPS.

Bewahren Sie meta.requestId aus der Antwort auf. Damit lässt sich eine bestimmte Anfrage untersuchen. Es ersetzt jedoch nicht die Release-ID und darf nicht als Secret verwendet werden.

Releases - Verbindungskontext prüfen

Lesen Sie den Kontext vor dem ersten Schreibvorgang. So prüfen Sie, ob die Adresse zur richtigen Datenbank führt und der ausgewählte Schlüssel die erforderlichen Scopes besitzt:

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"

Prüfen Sie in der Antwort:

  • data.apiVersion und data.contractVersion;
  • data.tenant.id, data.tenant.name und data.tenant.resolvedDomain;
  • data.caller.authentication mit dem Wert api_key;
  • das Vorhandensein von releases in data.capabilities.resources;
  • die dem Schlüssel zugewiesenen Scopes;
  • die Limits für Seiten, Batch, Dateien und Anfragen.

Wenn der Kontext auf eine andere Datenbank verweist oder ein erforderlicher Scope fehlt, halten Sie die Integration an und korrigieren Sie Adresse oder Schlüssel. Scopes können nicht durch eine einzelne Anfrage vergeben werden.

Releases - Berechtigungs-Scopes

Wählen Sie die Scopes des Schlüssels nach den Operationen aus, die die Integration ausführen muss. Für die vollständige Release-Unterstützung kann der folgende Satz verwendet werden:

releases:read
releases:write
releases:delete
releases:schema
releases:stats
releases:relationships:read
releases:relationships:write
releases:users:read
releases:users:write
releases:files:read
releases:files:write
releases:technical:read
releases:technical:write
releases:pin:write
releases:spam:write
releases:reopen:write
releases:rating:write
releases:escalation:write
releases:approval:write

Für das normale Lesen benötigen Sie releases:read. Schema und Statistiken erfordern jeweils releases:schema und releases:stats. Beziehungen, Benutzer und Dateien besitzen getrennte Lese- und Schreib-Scopes. Die Aktionen pin, spam, reopen, rating, escalation und approval benötigen ihre eigenen operativen Scopes.

Eine Beziehung zu einem anderen Objekt benötigt zusätzlich Lesezugriff auf das angegebene Modul, zum Beispiel assets:read, documents:read, tickets:read oder notes:read. Vergeben Sie Scopes nach dem Prinzip der geringsten Berechtigung.

Releases - Schema und Planungsfelder

Das Schema zeigt, welche Felder in einer bestimmten Datenbank gelesen und geschrieben werden können. Rufen Sie es ab, bevor Sie ein Formular oder eine Feldzuordnung vorbereiten:

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

Prüfen Sie bei jedem Feld unter anderem readable, writable, required, technical, unique und maxLength. Das Schema liefert außerdem Wörterbücher, verfügbare Beziehungsziele und Aktionen.

Für einen Release-Schreibvorgang sind derzeit mindestens subject und requesterEmail erforderlich. Releases besitzen eine zusätzliche Gruppe von Feldern für die Planung der Vorbereitung und Bereitstellung:

Feld
Bedeutung
Beispielverwendung
datePlannedStart
geplanter Beginn
Startzeit der Bereitstellung
datePlannedEnd
geplantes Ende
Endzeit der Bereitstellung
buildPlan
Plan für die Paketvorbereitung
Schritte zum Erstellen des Releases
testPlan
Testplan
Szenarien vor der Veröffentlichung
testResults
Testergebnisse
Ergebnis der durchgeführten Tests
implementationPlan
Bereitstellungsplan
Reihenfolge der Veröffentlichung in der Zielumgebung

Übergeben Sie Datumsfelder im ISO-8601-Format. Übernehmen Sie keine Diagnosefelder aus problems und keine Finanzfelder aus anderen Modulen in eine Release-Anfrage. Vergleichen Sie den Payload immer mit dem Releases-Schema.

Releases - wichtige Endpunkte

Die am häufigsten verwendeten Release-Routen sind:

  • GET /api/v1/releases - Release-Liste;
  • GET /api/v1/releases/{id} - einzelnes Release;
  • POST /api/v1/releases - Erstellung;
  • PATCH /api/v1/releases/{id} - teilweise Änderung;
  • DELETE /api/v1/releases/{id} - Löschen;
  • GET /api/v1/releases/schema - Schema für Felder und Beziehungen;
  • GET /api/v1/releases/stats - Statistiken;
  • GET /api/v1/releases/values - in Filtern verwendete Werte;
  • POST /api/v1/releases:batch - Erstellungs-, Änderungs- und Löschvorgänge.

Beziehungen, Benutzer, Dateien, Workflow-Aktionen und Genehmigungen haben eigene Routen. So kann eine Integration nur die Berechtigungen erhalten, die sie tatsächlich benötigt.

Releases - Auflistung und Pagination

Rufen Sie die Liste seitenweise ab. Geben Sie auch bei wenigen Datensätzen die Seitenzahl und Seitengröße ausdrücklich an:

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

Die Antwort enthält data.items sowie page, pageSize, totalItems, totalPages und hasNextPage. Rufen Sie weitere Seiten ab, solange hasNextPage den Wert true hat:

curl --request GET --url "$BASE_URL/api/v1/releases?page=2&pageSize=25&sort=dateUpdated&direction=desc" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Für eine Synchronisierung ist es meistens am bequemsten, nach dateUpdated zu sortieren und die zuletzt verarbeiteten Datensätze zu speichern. Setzen Sie pageSize nicht höher als das im Kontext zurückgegebene Limit.

Releases - Suche, Filter und Sortierung

Sie können Listenparameter miteinander kombinieren. Das folgende Beispiel sucht ein Release über seine Integrationskennung, begrenzt das Ergebnis auf den Typ release und einen Status, wählt Felder aus und sortiert anschließend nach dem Änderungsdatum:

curl --get --url "$BASE_URL/api/v1/releases" \
  --data-urlencode "itemType=release" \
  --data-urlencode "customId=PUBLIC-API-RELEASE-20260905133117-SOURCE" \
  --data-urlencode "status=Closed" \
  --data-urlencode "sort=dateUpdated" \
  --data-urlencode "direction=desc" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=25" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Für die tägliche Synchronisierung sind auch search, status, priority, subject, requesterEmail, source, externalNumber, referenceNumber, createdAfter, createdBefore, updatedAfter und updatedBefore nützlich, sofern sie im aktuellen Schema verfügbar sind.

Ein struktureller Filter hat das Format field:operator:value. Verfügbare Operatoren sind eq, ne, in, contains, startsWith, endsWith, empty, notEmpty, gt, gte, lt und lte:

curl --get --url "$BASE_URL/api/v1/releases" \
  --data-urlencode "filter=status:eq:Closed" \
  --data-urlencode "filter=buildPlan:contains:Paket" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=25" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Kodieren Sie Textwerte und Datumsangaben gemäß den URL-Regeln. Gehen Sie nicht davon aus, dass Wörterbücher in zwei Datenbanken identisch sind.

Releases - Felder auswählen und Daten einbeziehen

Mit dem Parameter fields begrenzen Sie die Antwort auf die von der Integration benötigten Felder. Der Parameter include fügt verknüpfte Daten hinzu:

curl --get --url "$BASE_URL/api/v1/releases/{RELEASE_ID}" \
  --data-urlencode "fields=subject,requesterEmail,status,priority,datePlannedStart,datePlannedEnd,buildPlan,testPlan,testResults,implementationPlan" \
  --data-urlencode "include=files,relationships,users" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Für das vollständige Modell können Sie fields=* verwenden. Das Einbeziehen von Dateien, Beziehungen und Benutzern erfordert die entsprechenden Lese-Scopes. fields umgeht weder die Zugriffskontrolle noch legt es technische Felder offen, für die der Schlüssel keine Berechtigung besitzt.

Achten Sie in der Antwort auf data.id, data.itemType, data.attributes und data.meta. Lesen Sie technische Felder wie pin oder isSpam, ändern Sie sie aber über die weiter unten beschriebenen dedizierten Aktionen.

Releases - Statistiken und Wörterbuchwerte

Mit Statistiken können Sie zum Beispiel die Verteilung der Releases nach Status prüfen. Dabei handelt es sich um einen Lesevorgang, der Datensätze nicht verändert:

curl --get --url "$BASE_URL/api/v1/releases/stats" \
  --data-urlencode "field=status" \
  --data-urlencode "limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Werte des Feldes buildPlan rufen Sie separat ab, wenn Sie Vorschläge oder Filter erstellen möchten:

curl --get --url "$BASE_URL/api/v1/releases/values" \
  --data-urlencode "field=buildPlan" \
  --data-urlencode "limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Rufen Sie zuerst das Wörterbuch ab und senden Sie erst danach den ausgewählten Wert im Body. Das ist besonders für status, priority, type und die in der jeweiligen Datenbank konfigurierten Planungsfelder wichtig.

Releases - Datensatz erstellen

Erstellen Sie ein neues Release mit POST /api/v1/releases. Geben Sie den technischen Typ release im Body und schreibbare Felder in attributes an. Das Beispiel enthält beschreibende Daten, Klassifizierung, Integrationskennungen und die vollständige Planungsgruppe:

curl --request POST --url "$BASE_URL/api/v1/releases" \
  --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: public-api-release-create-20260905133117" \
  --data-raw '{
    "itemType": "release",
    "attributes": {
      "customId": "PUBLIC-API-RELEASE-20260905133117-SOURCE",
      "subject": "Integrations-Release der Codenica API",
      "requesterEmail": "[email protected]",
      "description": "Release, das durch die Integration mit der Codenica Public API erstellt wurde.",
      "comments": "Beispiel für einen Bereitstellungsplan im Modul Releases.",
      "source": "Public API",
      "type": "Standard",
      "status": "Closed",
      "priority": "High",
      "impact": "Medium",
      "urgency": "High",
      "severity": "High",
      "services": "Codenica Public API",
      "tags": "public-api,release",
      "externalNumber": "EXT-PUBLIC-API-RELEASE-20260905133117",
      "referenceNumber": "REF-PUBLIC-API-RELEASE-20260905133117",
      "datePlannedStart": "2026-09-05T08:00:00Z",
      "datePlannedEnd": "2026-09-05T10:00:00Z",
      "buildPlan": "Vorbereitung des Release-Pakets.",
      "testPlan": "Funktionstests vor der Veröffentlichung.",
      "testResults": "Demonstrationstests erfolgreich abgeschlossen.",
      "implementationPlan": "Stufenweise Bereitstellung mit Rollback-Möglichkeit."
    },
    "customValues": [
      {
        "name": "description",
        "valuePattern": "[release-integration] PUBLIC-API-RELEASE-20260905133117"
      }
    ]
  }'

Das Minimum sind subject und requesterEmail, sofern das Schema keine zusätzlichen Anforderungen stellt. Speichern Sie nach der Erstellung data.id und den ETag aus dem Header sowie aus data.meta.etag. Das Secret des Schlüssels ist nicht Bestandteil der Release-Antwort.

Releases - Erstellung sicher wiederholen

Wenn das Ergebnis einer Anfrage unklar ist, wiederholen Sie exakt denselben Payload mit demselben Idempotency-Key. So verhindert die Integration die Erstellung eines zweiten Releases:

curl --request POST --url "$BASE_URL/api/v1/releases" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-release-create-20260905133117" \
  --data-binary @release.json

Verwenden Sie denselben Schlüssel nur für dieselbe Absicht und denselben Body. Erzeugen Sie für ein neues Release oder einen neuen Payload einen neuen Schlüssel. Ändern Sie den Schlüssel nach einem Timeout nicht, bevor Sie geprüft haben, ob der erste Schreibvorgang auf dem Server abgeschlossen wurde.

Releases - Datensatz und ETag lesen

Lesen Sie ein Release mit allen Feldern und den einbezogenen Daten:

curl --get --url "$BASE_URL/api/v1/releases/{RELEASE_ID}" \
  --data-urlencode "fields=*" \
  --data-urlencode "include=files,relationships,users" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Speichern Sie den ETag aus dem Antwort-Header. Er sollte data.meta.etag und meta.etag in der Antwort-Hülle entsprechen. Rufen Sie nach jedem erfolgreichen Schreibvorgang, jeder Aktion, Beziehungsänderung oder Dateioperation den neuen ETag ab oder lesen Sie ihn erneut.

Ein ETag repräsentiert die Version eines bestimmten Releases. Verwenden Sie den für ein Release gelesenen ETag nicht, um ein anderes zu ändern.

Releases - mit If-Match aktualisieren

Änderungen sind partiell. Senden Sie nur die zu ändernden Felder und geben Sie den aktuellen ETag im Header If-Match an:

curl --request PATCH --url "$BASE_URL/api/v1/releases/{RELEASE_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 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-update-20260905133117" \
  --data-raw '{
    "attributes": {
      "description": "Beschreibung durch die Integration aktualisiert.",
      "status": "Closed",
      "priority": "High",
      "datePlannedStart": "2026-09-05T09:00:00Z",
      "datePlannedEnd": "2026-09-05T11:00:00Z",
      "buildPlan": "Aktualisierter Plan für die Paketvorbereitung.",
      "testPlan": "Aktualisiertes Testszenario.",
      "testResults": "Testergebnisse nach der Korrektur.",
      "implementationPlan": "Aktualisierter Bereitstellungsplan."
    }
  }'

Ein gültiger If-Match liefert HTTP 200 und einen neuen ETag. Senden Sie in einem normalen PATCH weder schreibgeschützte Felder noch technische Felder, die von dedizierten Aktionen verwaltet werden.

Releases - mit einem veralteten If-Match umgehen

Ein Release kann gleichzeitig über das Panel oder eine andere Integration geändert werden. Die API schützt es vor versehentlichem Überschreiben:

curl --request PATCH --url "$BASE_URL/api/v1/releases/{RELEASE_ID}" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "alter-etag"' \
  --header "Idempotency-Key: public-api-release-stale-update-20260905133117" \
  --data-raw '{"attributes":{"description":"Diese Änderung erfordert einen erneuten Lesevorgang."}}'
  • 428 Precondition Required mit dem Code if_match_required bedeutet, dass der erforderliche Header If-Match fehlt.
  • 412 Precondition Failed mit dem Code if_match_failed bedeutet, dass der übergebene ETag nicht mehr aktuell ist.

Eine abgelehnte Anfrage darf das Release nicht ändern. Lesen Sie den Datensatz nach HTTP 412 erneut, ermitteln Sie den neuen ETag und entscheiden Sie dann, ob die Änderung wiederholt werden soll. Überschreiben Sie Änderungen einer anderen Person oder eines anderen Prozesses nicht ungeprüft.

Releases - Batch-Operationen

Der Batch-Endpunkt verarbeitet mehrere unabhängige Elemente in einer Anfrage. Das folgende Beispiel erstellt zwei Releases:

curl --request POST --url "$BASE_URL/api/v1/releases: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: public-api-release-batch-create-20260905133117" \
  --data-raw '{
    "items": [
      {
        "operation": "create",
        "create": {
          "itemType": "release",
          "attributes": {
            "customId": "PUBLIC-API-RELEASE-20260905133117-BATCH-A",
            "subject": "Batch-Release A",
            "requesterEmail": "[email protected]",
            "source": "Public API",
            "type": "Standard",
            "status": "Open",
            "priority": "Medium",
            "datePlannedStart": "2026-09-05T11:00:00Z",
            "datePlannedEnd": "2026-09-05T12:00:00Z",
            "buildPlan": "Build-Plan für Release A",
            "testPlan": "Testplan für Release A",
            "testResults": "Testergebnisse für Release A",
            "implementationPlan": "Bereitstellungsplan für Release A"
          }
        }
      },
      {
        "operation": "create",
        "create": {
          "itemType": "release",
          "attributes": {
            "customId": "PUBLIC-API-RELEASE-20260905133117-BATCH-B",
            "subject": "Batch-Release B",
            "requesterEmail": "[email protected]",
            "source": "Public API",
            "type": "Standard",
            "status": "Open",
            "priority": "Low",
            "datePlannedStart": "2026-09-05T13:00:00Z",
            "datePlannedEnd": "2026-09-05T14:00:00Z",
            "buildPlan": "Build-Plan für Release B",
            "testPlan": "Testplan für Release B",
            "testResults": "Testergebnisse für Release B",
            "implementationPlan": "Bereitstellungsplan für Release B"
          }
        }
      }
    ]
  }'

Prüfen Sie die Batch-Antwort für jedes Element einzeln. HTTP 200 bedeutet nicht, dass jedes Element erfolgreich war. Kontrollieren Sie succeeded, failed, IDs und Fehler der einzelnen Elemente.

Änderung und Löschung verwenden denselben Endpunkt:

{
  "items": [
    {
      "operation": "update",
      "id": "{RELEASE_ID}",
      "ifMatch": "\"{CURRENT_ETAG}\"",
      "update": {
        "attributes": {
          "datePlannedStart": "2026-09-05T09:30:00Z",
          "buildPlan": "Aktualisierter Plan für die Paketvorbereitung"
        }
      }
    },
    {
      "operation": "delete",
      "id": "{OTHER_RELEASE_ID}",
      "ifMatch": "\"{OTHER_CURRENT_ETAG}\""
    }
  ]
}

Verwenden Sie bei Änderung und Löschung den ETag des jeweiligen Datensatzes. Der Idempotenzschlüssel identifiziert die gesamte Batch-Anfrage, nicht ein einzelnes Element. Ein Batch ist keine Transaktion. Verarbeiten Sie daher das Ergebnis jedes Elements einzeln.

Releases - Beziehungen zu Objekten

Die verfügbaren Beziehungsziele werden von /api/v1/releases/schema zurückgegeben. Das Schema kann unter anderem die Sammlungen assets, documents, changes, tickets, problems, releases, notes, approvals, worktasks und requesteditems angeben.

Dass ein Ziel im Schema steht, bedeutet nicht, dass in der aktuellen Datenbank ein verwendbarer Datensatz vorhanden ist. Prüfen Sie vor dem Hinzufügen einer Beziehung die Berechtigungen, die Ziel-ID und den itemType des Ziels. Verwenden Sie für assets, documents, tickets, changes, problems und releases den im Schema angegebenen Beziehungstyp, zum Beispiel related. Für notes, approvals, worktasks und requesteditems kann relationshipType null sein. Erzwingen Sie related nicht, wenn das Schema den Wert nicht vorgibt.

Mehrere Beziehungen per Batch hinzufügen:

curl --request POST --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/relationships:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-relationship-batch-20260905133117" \
  --data-raw '{
    "add": [
      {
        "targetId": "{ASSET_ID}",
        "targetDataSet": "assets",
        "targetItemType": "computer",
        "relationshipType": "related"
      },
      {
        "targetId": "{DOCUMENT_ID}",
        "targetDataSet": "documents",
        "targetItemType": "document",
        "relationshipType": "related"
      },
      {
        "targetId": "{NOTE_ID}",
        "targetDataSet": "notes",
        "targetItemType": "note",
        "relationshipType": null
      }
    ],
    "remove": []
  }'

La réponse HTTP 200 contient les compteurs added, removed et skipped. Rufen Sie nach dem Vorgang die Beziehungssammlung ab und prüfen Sie, ob das Ergebnis den Erwartungen entspricht.

Releases - Beziehungen lesen und entfernen

Rufen Sie die Beziehungssammlung über ihre eigene Route ab:

curl --request GET --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/relationships?page=1&pageSize=100" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Sie können eine einzelne Beziehung ohne Batch hinzufügen und sie anschließend mit dem aktuellen ETag entfernen:

curl --request POST --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/relationships" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-relationship-20260905133117" \
  --data-raw '{"targetId":"{TICKET_ID}","targetDataSet":"tickets","targetItemType":"ticket","relationshipType":"related"}'

curl --request DELETE --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/relationships/tickets/{TICKET_ID}?relationshipType=related" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-relationship-delete-20260905133117"

Wenn das Schema für ein Ziel relationshipType: null zurückgibt, lassen Sie den Query-Parameter relationshipType in der Löschroute weg. Beziehungen können auch über eine partielle Änderung des Releases entfernt werden:

curl --request PATCH --url "$BASE_URL/api/v1/releases/{RELEASE_ID}" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-relationship-patch-20260905133117" \
  --data-raw '{"relationshipsToRemove":[{"targetId":"{TICKET_ID}","targetDataSet":"tickets","targetItemType":"ticket","relationshipType":"related"}]}'

Lesen Sie das Release oder die Beziehungssammlung nach einer Änderung erneut. Der ETag kann sich ändern. Verwenden Sie den alten ETag daher nicht für die nächste Aktion.

Releases - Beziehungen zu Benutzern

Ein Release kann die Benutzerbeziehungen agent, watcher und appUserRequester besitzen. Die erste bezeichnet die für die Bearbeitung verantwortliche Person, die zweite einen Beobachter und die dritte den anfordernden Anwendungsbenutzer. Fügen Sie keine Beziehungen hinzu, die das Schema nicht zurückgibt.

Einen Agenten zuweisen:

curl --request POST --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/user-relationships" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-agent-20260905133117" \
  --data-raw '{"targetId":"{USER_ID}","targetDataSet":"users","relationshipType":"agent"}'

Einen Beobachter per Batch hinzufügen:

curl --request POST --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/user-relationships:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-watcher-20260905133117" \
  --data-raw '{"add":[{"targetId":"{WATCHER_ID}","targetDataSet":"users","relationshipType":"watcher"}],"remove":[]}'

Beziehungen lesen und entfernen:

curl --request GET --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/user-relationships?page=1&pageSize=100" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

curl --request DELETE --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/user-relationships/users/{USER_ID}?relationshipType=agent" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-agent-delete-20260905133117"

Einen Beobachter können Sie auch über user-relationships:batch entfernen, indem Sie ein leeres add-Array und einen Eintrag in remove senden. Lesen Sie nach jeder Änderung den neuen ETag.

Releases - Dateien

Lesen Sie vor einer Dateioperation das aktuelle Release und seinen ETag. Für den Upload ist das Format multipart/form-data erforderlich:

curl --request POST --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/files?relationshipType=documentation" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-file-20260905133117" \
  --form "[email protected];type=text/plain"

Dateiliste und Download des Inhalts:

curl --request GET --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/files?page=1&pageSize=100" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

curl --request GET --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/files/{FILE_ID}/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output release-evidence.txt

Ein Listenelement enthält unter anderem id, name, fileName, contentType, size, relationshipType, isMain und downloadUrl. Behandeln Sie downloadUrl als API-Pfad und nicht als öffentlichen anonymen Link.

Sie können eine vorhandene Datei an ein anderes Release anhängen und die Beziehung anschließend entfernen:

curl --request POST --url "$BASE_URL/api/v1/releases/{OTHER_RELEASE_ID}/files/{FILE_ID}?relationshipType=manual" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{OTHER_RELEASE_CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-file-attach-20260905133117"

curl --request DELETE --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/files/{FILE_ID}" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-file-delete-20260905133117"

Prüfen Sie vor dem Löschen das Release, die fileId und den aktuellen ETag. Ermitteln Sie das Größenlimit aus dem Kontext. Laden Sie eine Datei nicht in den Speicher, bevor Sie das Limit geprüft haben.

Releases - Anheften, Spam und Wiedereröffnung

Workflow-Aktionen besitzen eigene Endpunkte. Ersetzen Sie sie nicht durch einen gewöhnlichen PATCH, wenn die API eine dedizierte Aktion anbietet. Jede Aktion benötigt den aktuellen ETag und einen eigenen Idempotenzschlüssel.

Ein Release anheften und als Spam markieren:

curl --request POST --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/pin" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-pin-20260905133117" \
  --data-raw '{"pin":2}'

curl --request POST --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/spam" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-spam-on-20260905133117" \
  --data-raw '{"isSpam":true}'

Heben Sie die Spam-Markierung auf, indem Sie {"isSpam":false} an dieselbe Route senden. Öffnen Sie ein Release erneut:

curl --request POST --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/reopen" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-reopen-20260905133117"

Aktionen können den ETag ändern. Lesen Sie nach jeder Aktion die Antwort und das aktuelle Release, bevor Sie die nächste Aktion ausführen.

Releases - Bewertung und Eskalation

Eine Bewertung kann gleichzeitig Feedback übermitteln und eine Eskalationsanfrage registrieren:

curl --request POST --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/rating" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-rating-20260905133117" \
  --data-raw '{
    "rating": 4,
    "feedback": "Bewertung aus einer Public API-Integration.",
    "isEscalationRequested": true,
    "escalationRequestReason": "Das Release erfordert eine Analyse durch das Team der zweiten Supportstufe."
  }'

Für eine reine Bewertung benötigen Sie releases:rating:write. Eine Eskalationsanfrage benötigt zusätzlich releases:escalation:write. Lesen Sie das Release nach dem Vorgang erneut und prüfen Sie die gespeicherten Bewertungs- und Eskalationsfelder. Gehen Sie nicht davon aus, dass HTTP 200 allein bedeutet, dass jeder Wert gespeichert wurde.

Releases - Genehmigung und Entscheidung

Eine Genehmigung ist ein eigenes Objekt, das mit einem Release verknüpft werden kann. Für ihre Erstellung benötigen Sie die Scopes des Moduls approvals und releases:approval:write:

curl --request POST --url "$BASE_URL/api/v1/approvals" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-release-approval-create-20260905133117" \
  --data-raw '{
    "itemType": "approval",
    "approverId": "{APPROVER_USER_ID}",
    "attributes": {
      "customId": "PUBLIC-API-RELEASE-20260905133117-APPROVAL",
      "category": "Public API",
      "description": "Genehmigung des Release-Plans."
    },
    "relationships": [
      {
        "targetId": "{RELEASE_ID}",
        "targetDataSet": "releases",
        "targetItemType": "release"
      }
    ]
  }'

Lesen Sie die Genehmigung nach der Erstellung über ihren Endpunkt und speichern Sie anschließend die Entscheidung über den Release-Endpunkt:

curl --request POST --url "$BASE_URL/api/v1/releases/{RELEASE_ID}/approvals/{APPROVAL_ID}" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-approval-decision-20260905133117" \
  --data-raw '{"approve":true,"remark":"Der Release-Plan wurde durch die Public API-Integration genehmigt."}'

Lesen Sie die Genehmigung nach der Entscheidung erneut und prüfen Sie ihren Status oder dateApproved. So bestätigen Sie, dass die Entscheidung gespeichert wurde und nicht nur, dass der Server die Anfrage angenommen hat.

Releases - Datensatz löschen

Zum Löschen benötigen Sie den aktuellen ETag und einen Idempotenzschlüssel:

curl --request DELETE --url "$BASE_URL/api/v1/releases/{RELEASE_ID}" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header 'If-Match: "{CURRENT_ETAG}"' \
  --header "Idempotency-Key: public-api-release-delete-20260905133117"

Führen Sie nach HTTP 200 einen überprüfenden GET aus. Das gelöschte Release sollte HTTP 404 mit dem Code release_not_found oder dem im Vertrag angegebenen entsprechenden Code zurückgeben. Wenn das Objekt Beziehungen oder Dateien besitzt, prüfen Sie vor dem Löschen die Folgen im Schema und in den Regeln Ihrer Datenbank.

Releases - Fehler, Limits und Sicherheit

Erfolgreiche Antworten liefern die Daten im Feld data. Technische Informationen wie requestId und manchmal ein ETag stehen in meta. Fehler verwenden das Problem-Details-Format mit status, code, detail und requestId.

  • 400 - ungültiger Body, Parameter oder Feldwert;
  • 401 - fehlende oder ungültige Authentifizierung;
  • 403 - fehlender Scope oder fehlender Datenbankzugriff;
  • 404 - Release, Datei oder Beziehungsziel ist nicht vorhanden oder nicht sichtbar;
  • 409 - Daten- oder Idempotenzkonflikt;
  • 412 - veralteter 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.

Beachten Sie die im Kontext zurückgegebenen Limits für pageSize, Batch-Elemente, Dateien, Beziehungen und Rate-Limit. Lesen Sie X-RateLimit-Limit, X-RateLimit-Remaining und bei 429 Retry-After. Verwenden Sie kontrollierte Wiederholungen mit wachsender Verzögerung.

Verwenden Sie bei datenverändernden Operationen immer einen eindeutigen Idempotency-Key, den aktuellen If-Match, wenn der Endpunkt ihn verlangt, und den neuen ETag nach einer erfolgreichen Änderung. Nach einem Timeout ermitteln Sie das Ergebnis zuerst mit GET oder wiederholen dieselbe Anfrage mit demselben Schlüssel. Bewahren Sie Client ID und Client Secret außerhalb des Quellcodes auf, schreiben Sie sie nicht in Logs und senden Sie sie nicht in Gesprächen oder Tickets.

Releases - Reihenfolge der Integrationsschritte

  1. Bestimmen Sie die richtige Cloud-Adresse oder die tatsächliche Adresse der On-Premise-Installation.
  2. Erstellen Sie unter Einstellungen - API - API Keys einen eigenen Schlüssel für Anwendung und Umgebung.
  3. Vergeben Sie nur die für Releases und geplante Beziehungen erforderlichen Scopes.
  4. Senden Sie GET /api/v1/context und prüfen Sie Datenbank, Caller, Scopes und Limits.
  5. Rufen Sie GET /api/v1/releases/schema ab und erstellen Sie die Feldzuordnung.
  6. Rufen Sie die Liste mit Pagination, Suche oder Filtern ab.
  7. Erstellen Sie ein Release mit POST und einem neuen Idempotency-Key.
  8. Speichern Sie UUID und ETag.
  9. Lesen Sie vor jeder Änderung den aktuellen Datensatz und seinen ETag.
  10. Führen Sie Änderungen, Beziehungen, Dateioperationen und Workflow-Aktionen mit dem konkreten ETag und einem neuen Idempotenzschlüssel aus.
  11. Speichern Sie nach jeder erfolgreichen Mutation den neuen ETag und lesen Sie das Ergebnis erneut.
  12. Lesen Sie nach 412 den Datensatz, lösen Sie den Konflikt und wiederholen Sie die Operation erst danach.
  13. Verwenden Sie bei vielen Änderungen Batch, prüfen Sie aber den Status jedes Elements, da ein Batch keine Transaktion ist.
  14. Prüfen Sie bei einer Genehmigung ihren Status nach der Entscheidung.
  15. Verwenden Sie beim Löschen den aktuellen ETag und bestätigen Sie mit einem späteren GET HTTP 404.

Mit diesem Ablauf können Sie die Planung und Bereitstellung von Releases synchronisieren, ohne sich auf zufällige Annahmen über Felder, Beziehungen oder die Installationsadresse zu stützen.