REST-API¶

Die neue HTTP/JSON-API stellt fachliche Operationen des MCP-Katalogs ohne JSON-RPC-Umschlag bereit. Die verfügbaren Operationen hängen vom installierten Serverstand ab. Die API ist operationsorientiert, keine separate CRUD-Schnittstelle für jede Datenbanktabelle.

Zugang und Berechtigungen¶

Verwenden Sie einen vorhandenen MCP-API-Schlüssel als Authorization: Bearer <Schlüssel>. MCP muss global und für das betreffende Projekt freigegeben sein. Ein Projekt-Schlüssel benötigt zusätzlich X-ZTM-Project-UniqueId. Ein globaler Schlüssel benötigt ausdrücklich Projektzugriff, wenn er Projektoperationen aufruft. Browseranmeldung und Windows-Anmeldung ersetzen den API-Schlüssel nicht.

Benutzerrechte, Schreibfreigaben, erlaubte Fähigkeiten und Demo-Beschränkungen gelten wie bei MCP. Nutzen Sie außerhalb lokaler Tests ausschließlich HTTPS. Schlüssel gehören nicht in URLs, Quellcode oder Protokolle. Weitere Grundlagen stehen unter Sichere Aktionen und MCP.

Funktionen entdecken¶

Die OpenAPI-Beschreibung enthält konkrete POST-Pfade für die verfügbaren Operationen. Eingaben werden aus denselben Schemas wie MCP erzeugt. Projektanhänge, Releasevergleiche und gespeicherte Vergleiche besitzen typisierte Ausgabeschemas. Ältere dynamische Query-/Aktionsantworten bleiben erweiterbare JSON-Objekte; vollständige SDK-Typisierung aller bestehenden Operationen ist noch nicht vorhanden. Der Katalog kann gemeinsame Query- und Aktionswerkzeuge enthalten; nicht jeder Web-Menüpunkt hat einen eigenen Endpunkt.

$headers = @{
    Authorization = "Bearer $env:ZTM_API_KEY"
    'X-ZTM-Project-UniqueId' = $env:ZTM_PROJECT_UNIQUE_ID
}
$baseUrl = 'https://ihr-server.example'
Invoke-RestMethod "$baseUrl/api/v1/operations" -Headers $headers
Invoke-RestMethod "$baseUrl/api/v1/operations/ztm_usage_guide" `
    -Method Post -Headers $headers -ContentType 'application/json' -Body '{}'

Die zwei Umgebungsvariablen im Beispiel werden vom aufrufenden PowerShell-Skript gelesen; sie konfigurieren nicht automatisch den Server. Projekt-Routing gehört in die Header, nicht in den Argumentkörper. JSON-Bodies dürfen höchstens 1 MiB groß und 32 Ebenen tief sein. Doppelte JSON-Schlüssel werden abgelehnt.

Schreiben und Exporte¶

Verwenden Sie für Änderungen die im jeweiligen Vertrag vorgesehene Vorschau und ausdrückliche Bestätigung, beispielsweise ztm_project_action_prepare und ztm_project_action_commit. API-Zugang allein ersetzt keine fachliche Freigabe. Halten Sie Vorschau, Idempotenzschlüssel und Bestätigung an denselben Benutzer-/Projektkontext gebunden. Nach einem Timeout nicht blind erneut schreiben; zunächst den jeweiligen Aktionsstatus prüfen.

Ein Export kann eine resourceUri liefern. Lesen Sie sie mit POST /api/v1/resources/read und dem Body {"uri":"<resourceUri>"} unter demselben Schlüssel und Projekt. Die Antwort enthält contents mit Text oder Base64-Daten und MIME-Typ. Tickets können ablaufen oder nur einmal lesbar sein; behandeln Sie die URI vertraulich.

Fehler¶

Fehler liefern HTTP-Status und application/problem+json mit code und traceId: 400 ungültige Eingabe, 401 fehlende/abgelehnte Authentifizierung, 403 fehlende Berechtigung, 404 nicht verfügbares Objekt oder Operation, 409 Aktionskonflikt, 413 zu großer Body, 415 falscher Inhaltstyp, 500 interner Fehler. Konflikte benötigen erneute Prüfung statt automatischer Wiederholung. Beim Support die traceId, niemals Schlüssel oder vertrauliche Nutzdaten angeben.

Voraussetzungsregeln und gesperrte Tests¶

ztm_project_query liefert bei Bibliotheks- und geplanten Abhängigkeiten das Feld rule: 0 = Nur Hinweis, 1 = Muss erfolgreich sein, 2 = Darf nicht fehlgeschlagen sein.

Zum Ändern einer bestehenden Bibliotheks-Abhängigkeit verwenden Sie ztm_project_action_context, anschließend ztm_project_action_prepare mit capabilityId: project.test-case.dependency.set-rule und den Argumenten testCaseId, dependencyId, rule. Prüfen Sie die Vorschau und bestätigen Sie sie mit ztm_project_action_commit. Der Schlüssel benötigt diese Fähigkeit ausdrücklich als Schreibfreigabe. Anlegen bleibt kompatibel: Eine neue Beziehung beginnt als Hinweis; danach kann ihre Regel geändert werden. Bestehende Testpläne und Testläufe werden dabei nicht automatisch synchronisiert.

POST /api/v1/operations/ztm_test_prerequisites_read mit {"plannedVariantId":123} prüft die Voraussetzungen eines sichtbaren geplanten Testfalls. Die Antwort enthält isBlocked, needsRecheck und blockers. Nicht sichtbare oder nicht mehr vorhandene Vorgänger werden nicht namentlich ausgegeben; dafür steht hasHiddenPrerequisites. Diese Momentaufnahme erteilt keine Ausführungsberechtigung und ersetzt keine persönliche Nachtestbestätigung. Dieselbe Operation steht über MCP zur Verfügung.

Projektanhänge¶

ztm_project_attachments_read liefert mit offset und limit (höchstens 100) die Projektanhänge und deren ownerId. Mit attachmentId liefert dieselbe Operation den Dateiinhalt als contentBase64 (höchstens 32 MiB). Voraussetzung ist ein aktiver Projektadministrator oder Projektmanager. Dynamisch verknüpfte Dateien werden aufgelistet, aber nicht über diese Operation heruntergeladen.

Für Schreibzugriffe benötigt der Schlüssel die jeweils eigene Fähigkeit project.attachment.upload, project.attachment.update oder project.attachment.delete. Die bisherigen Planungsanhang-Freigaben reichen hierfür nicht aus. Verwenden Sie den im Leseergebnis gelieferten ownerId; er kann bei einem Projekt 0 sein.

1. Upload: ztm_project_attachment_stage mit targetKind: "project", targetId: <ownerId>, fileName, mimeType und contentBase64 aufrufen. Pro Datei gilt hier das bestehende Limit von 512 KiB.
2. ztm_project_action_prepare mit der passenden Fähigkeit, einem neuen idempotencyKey und arguments aufrufen. Für Upload: ownerKind: "project", ownerId, attachmentReferenceId aus dem Staging-Ticket sowie optional displayName und remarks. Für Metadatenänderung: ownerKind, ownerId, attachmentId, displayName, remarks. Für Löschen: ownerKind, ownerId, attachmentId.
3. Vorschau prüfen und mit ztm_project_action_commit unter demselben Schlüssel bestätigen. Änderungen nach der Vorschau verursachen einen Konflikt; eine bestätigte Wiederholung erzeugt keinen zweiten Anhang.

Releasevergleiche und Entscheidungen¶

ztm_release_snapshots_list listet lesbare gespeicherte Vergleiche mit optionalem targetId-Filter. Für die nächste Seite den zurückgegebenen NextCursor als cursor übergeben.

ztm_release_compare erwartet baseId, targetId, explizite baseRunIds/targetRunIds und gegebenenfalls baseScopeRunIds/targetScopeRunIds als Listen von { "runId": 123, "scopeRunId": 123 }. Optionale baseSnapshotId/targetSnapshotId wählen gespeicherte Evidenz. Das Ergebnis entspricht dem Webvergleich einschließlich Fingerprint; Auswahl und Objektberechtigungen werden fachlich geprüft.

Zum Speichern: Fähigkeit project.release-review.snapshot-create ausdrücklich freigeben und über Prepare/Commit die Argumente query (das Vergleichsargumentobjekt), name und fingerprint übergeben. Veränderte Evidenz wird nicht still gespeichert. ztm_release_snapshot_read liest danach mit snapshotId den gespeicherten Vergleich, decisionRevision und die Entscheidungshistorie; historyBeforeRevision blättert ältere Entscheidungen.

Eine Entscheidung benötigt zusätzlich project.release-review.decision-record, Projektverwaltungsrechte und eine ausdrücklich vom Menschen beauftragte Bestätigung. Prepare erwartet snapshotId, targetId, revision, outcome (1 angenommen, 2 mit Auflagen angenommen, 3 abgelehnt, 4 widerrufen), responsibleUserId, comment, openPoints (ein Punkt je Zeile) und humanConfirmed: true. Der angemeldete Akteur wird serverseitig protokolliert; das Flag ist kein Ersatz für seine tatsächliche Freigabe. Danach Vorschau prüfen und committen. Dieselben Regeln wie im Web gelten: aktuelle Revision, zulässige verantwortliche Person, Begründung, vollständiger Prüfungsumfang und unveränderte Evidenz; historische Projektkopien dürfen nicht neu entschieden werden.

Umfang und Grenzen¶

REST und MCP teilen sich den Operationskatalog. Daraus folgt keine vollständige Abdeckung sämtlicher Web-Funktionen. Projektanhänge besitzen jetzt einen eigenen Schreibvertrag; Uploadverträge für Testfälle, Anforderungen und Planung bleiben davon getrennt. Beliebige Serverdateipfade und Local-Bridge-Dateiverknüpfungen werden nicht als allgemeine API-Aktion angeboten. Eigenständiges Variantenkopieren und Manifest-Dateiimporte sind auch im geprüften Web-Stand keine eigenen Funktionen; vorhandene Varianten- und Manifeständerungen bleiben nutzbar. Die bisher zurückgestellten Einzeloperationen sind im Capability-Katalog erkennbar.

Reine Browserdarstellung, Dateiauswahldialoge und interaktive Anmeldung benötigen keinen eigenen Fachendpunkt. Persönliche Bestätigungen eines tatsächlich durchgeführten manuellen Nachtests werden nicht automatisch im Namen eines Prüfers erzeugt. Release-Überblick/PDF und Automationsimporte nutzen ihre vorhandenen Operationen; die REST-API erweitert deren fachlichen Umfang nicht.

Testfall-Versionen¶

Die Testfall-Versionierung ist über POST /api/v1/operations/ztm_project_test_case_versions erreichbar. Mit operation: "list", testCaseID sowie optional skip und take erhalten Sie eine begrenzte Liste mit aktuellem Head. read benötigt zusätzlich revisionID, compare außerdem otherRevisionID; asset verwendet revisionID und assetID und liefert die Bytes base64-kodiert. restore-preview prüft revisionID gegen expectedHead.

Eine Wiederherstellung wird mit ztm_project_action_prepare, Capability project.test-case-version.restore, und Argumenten testCaseID, revisionID, expectedHead, optional note und options vorbereitet. Danach den gelieferten Token mit ztm_project_action_commit bestätigen. options kann ausdrücklich ausgeschlossene excludedAttributeIDs und flattenUnavailableReusableSteps enthalten. Projektbindung, aktive Benutzeridentität, Objektberechtigungen, Schreib-Scopes und Demo-Schutz gelten weiterhin. API-Schlüssel nicht in Beispiele, Protokolle oder die Befehlszeilenhistorie schreiben.