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.

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.