OpenAPI verwenden

Workspace stellt eine OpenAPI-Spezifikation für technische Analyse, Contract-Checks, Client-Generierung und Privacy-Prüfung bereit. Diese Seite zeigt, wie Sie die Datei beziehen, lesen und sinnvoll einsetzen.

Die vollständige OpenAPI-Datei ist nicht Teil dieses Public-Docs-Builds. Sie wird von der jeweiligen Workspace-Instanz erzeugt und beschreibt den Stand dieser laufenden Serverversion.

Wann OpenAPI hilft

Nutzen Sie OpenAPI, wenn Sie:

verfügbare Pfade, Methoden und DTO-Strukturen prüfen möchten,
Request- und Response-Schemas für Integrationen auswerten,
Testclients oder typisierte DTOs generieren,
Vertragsänderungen zwischen Versionen vergleichen,
Privacy-Metadaten wie x-nucleus-privacy auswerten.

Nutzen Sie OpenAPI nicht als Ersatz für Runtime-Discovery. Wenn Workspace für einen Kontext Discovery, Entry Points oder Ressourcen-Meta veröffentlicht, verwenden Clients diese Laufzeitverträge.

OpenAPI-Datei abrufen

Die OpenAPI-Spezifikation liegt auf einer laufenden Workspace-Instanz unter:

text

/api/v1/docs/openapi.json

Dieser Endpunkt ist für lokale Diagnose und Betreiberzugriff gedacht. Er ist loopback-geschützt und wird nicht als allgemein öffentlicher Internet-Endpunkt behandelt.

Rufen Sie die Datei deshalb auf dem Server selbst oder über ein SSH-Portforwarding ab:

bash

ssh -L 18080:127.0.0.1:8080 ops@workspace-host
curl -fsS http://127.0.0.1:18080/api/v1/docs/openapi.json -o openapi.json

Ersetzen Sie 8080 durch den lokalen Port, auf dem Ihre Workspace-Instanz auf dem Server lauscht.

Im Browser ansehen

Workspace stellt für lokale Diagnose zusätzlich eine Scalar-Ansicht bereit:

text

/api/v1/docs/

Auch diese Ansicht ist loopback-geschützt. Öffnen Sie sie lokal auf dem Server oder über denselben SSH-Tunnel:

text

http://127.0.0.1:18080/api/v1/docs/

Die Ansicht lädt openapi.json relativ aus demselben Pfad.

Tenant-Kontext setzen

Viele Workspace-APIs sind tenantgebunden. Authentifizierung allein wählt bei nicht sessiongebundenen API-Aufrufen keinen Tenant aus. Setzen Sie deshalb für tenantgebundene Requests den Header X-Tenant-ID auf die UUID des Mandanten, sofern Ihre Session oder Ihr Credential nicht bereits fest an einen Tenant gebunden ist:

http

Authorization: Basic <credentials>
X-Tenant-ID: 11111111-1111-1111-1111-111111111111
Accept: application/json

Das gilt auch, wenn Sie die OpenAPI-Datei in ein API-Tool wie Bruno importieren: Prüfen Sie nach dem Import, ob X-Tenant-ID als Header gesetzt ist. Verwenden Sie die Tenant-UUID, nicht einen lokalen Profilalias wie stage-shop oder mandant-a.

Wenn ein Request mit 403 ERR_TENANT_REQUIRED und dem Hinweis Tenant selection required fehlschlägt, war die Identity zwar authentifiziert, aber der Request hatte keinen aktiven Tenant-Kontext. Setzen Sie X-Tenant-ID, prüfen Sie die UUID und stellen Sie sicher, dass die authentifizierte Identity Mitglied dieses Tenants ist.

Für die fachliche Einordnung von Benutzerkonto, Mitgliedschaft, Profilbindung, aktiver Sitzung und System-Mandant nutzen Sie Mandanten, Benutzerkonten und Systemsicht.

Datei prüfen

Prüfen Sie zuerst, ob die Datei lesbar ist und wie viele Pfade sie enthält:

bash

jq '.openapi, .info.title, .info.version, (.paths | keys | length)' openapi.json

Für einen schnellen Überblick über veröffentlichte Pfade:

bash

jq -r '.paths | keys[]' openapi.json | sort

Für Methoden eines bestimmten Pfads:

bash

jq '.paths["/api/v1/meta/discovery"] | keys' openapi.json

OpenAPI-Struktur lesen

Die wichtigsten Bereiche sind:

Bereich	Bedeutung
`openapi`	Version des OpenAPI-Formats.
`info`	Titel, Version und Beschreibung der Spezifikation.
`paths`	HTTP-Pfade mit Methoden, Parametern, Request-Body und Responses.
`components.schemas`	Wiederverwendbare DTO- und Schema-Definitionen.
`components.securitySchemes`	Beschreibt Authentifizierungsschemata wie Bearer- oder BasicAuth.
`paths...security`	Beschreibt Sicherheitsanforderungen einer geschützten Operation.
`tags`	Gruppiert Endpunkte thematisch, wenn der Generator Tags setzt.

Ein Pfad beschreibt die technische Form eines HTTP-Vertrags. Prüfen Sie dort:

Methode, zum Beispiel get, post, patch oder delete,
parameters für Pfad- und Query-Parameter,
Header-Parameter wie X-Tenant-ID für tenantgebundene Operationen,
requestBody für schreibende JSON-Payloads,
responses für Antwortstruktur und Statusklassen,
Schema-Referenzen unter $ref.

Schemas interpretieren

Viele Operationen verweisen auf Schemas in components.schemas:

bash

jq '.components.schemas | keys[]' openapi.json

Wenn eine Operation auf ein Schema verweist, lösen Sie den $ref auf:

bash

jq '.components.schemas.ProductVariant' openapi.json

Beachten Sie dabei:

readOnly-Felder kommen aus dem Server und gehören normalerweise nicht in Create- oder Update-Payloads.
writeOnly-Felder dürfen in Requests vorkommen, erscheinen aber nicht zwingend in Antworten.
required beschreibt technische Pflichtfelder des Schemas, ersetzt aber keine fachliche Validierung.
Enum-Werte beschreiben bekannte technische Werte. Prüfen Sie trotzdem Ressourcen-Meta, wenn eine Ressource zur Laufzeit eigene Optionen veröffentlicht.

Privacy-Metadaten auswerten

Workspace kann Felder in OpenAPI mit x-nucleus-privacy markieren. Nutzen Sie nucli privacy, wenn Sie diese Felder gezielt auswerten möchten:

bash

nucli privacy --file openapi.json --json
nucli privacy --file openapi.json --path /api/v1/contacts --json
nucli privacy --file openapi.json --category contact.email
nucli privacy --file openapi.json --classification personal

Ein leerer Treffer bedeutet nicht automatisch, dass eine fachliche Antwort frei von Personen- oder Geschäftsdaten ist. Er bedeutet nur, dass die geprüfte Spezifikation keine passende Privacy-Annotation enthält.

Mit Discovery kombinieren

OpenAPI beschreibt technische Strukturen. Für robuste Clients brauchen Sie trotzdem Runtime-Discovery:

Aufgabe	Verwenden
Serverfähigkeit vor Login prüfen	`GET /api/v1/meta/discovery`
Öffentliche Auth- und Onboarding-Einstiege finden	`GET /api/v1/meta/entrypoints`
Tenantgebundene Ressourcen finden	`GET /api/v1/profile/entrypoints`
Erlaubte Aktionen und Felder einer Ressource prüfen	`GET /api/v1/{resource}/_meta`
DTO-Strukturen und Privacy-Annotationen analysieren	`openapi.json`

Starten Sie Integrationen daher discovery-first. Verwenden Sie OpenAPI für Analyse, Tests, Codegenerierung und Vertragsvergleich, aber bauen Sie kontextabhängige Aktions-URLs aus den vom Server veröffentlichten Runtime-Verträgen.

OpenAPI zwischen Versionen vergleichen

Speichern Sie Spezifikationen versioniert in einem geschützten Arbeitsbereich:

bash

curl -fsS http://127.0.0.1:18080/api/v1/docs/openapi.json -o openapi-2.31.0.json
curl -fsS http://127.0.0.1:18081/api/v1/docs/openapi.json -o openapi-2.32.0.json

Vergleichen Sie zuerst Pfade:

bash

jq -r '.paths | keys[]' openapi-2.31.0.json | sort > paths-old.txt
jq -r '.paths | keys[]' openapi-2.32.0.json | sort > paths-new.txt
diff -u paths-old.txt paths-new.txt

Vergleichen Sie danach gezielt Schemas, die Ihre Integration nutzt. Ein reiner OpenAPI-Diff ersetzt keine fachlichen Regressionstests gegen eine laufende Workspace-Instanz.

Grenzen

OpenAPI beantwortet nicht jede Integrationsfrage.

Wichtig:

Die Public Docs werden nicht aus openapi.json generiert.
Diese Seite erklärt den Umgang mit der Spezifikation, sie ist keine vollständige API-Referenz.
Die Spezifikation beschreibt den Stand der laufenden Serverversion.
Rechte, Tenant-Kontext, aktivierte Funktionen und veröffentlichte Ressourcen können zur Laufzeit variieren.
Verwenden Sie für konkrete Ressourcenaktionen weiterhin Discovery und Ressourcen-Meta.

Nächste Schritte

CLI und reproduzierbare API-Aufrufe: Lesen Sie CLI und API.

Discovery und Ressourcen-Meta: Lesen Sie Discovery und Ressourcen.

Storefront- und Commerce-Verträge: Starten Sie mit B2B-Onlineshop bauen.