API-Discovery

WebBlocks CMS stellt eine Discovery-first-Content-API für vertrauenswürdige KI- und Operator-Tools bereit. Ein externes Tool sollte nur die CMS-API-Basis-URL und ein CMS-API-Token benötigen, um die verfügbaren Endpunkte, Schemata, Beispiele und den sicheren Content-Workflow kennenzulernen.

Basis-URL

/webadmin/api

Speichern Sie für lokale KI-/Operator-Tools die API-Basis-URL statt der öffentlichen Site-Wurzel:

WEBBLOCKS_CMS_API_URL=https://example.com/webadmin/api
WEBBLOCKS_CMS_API_TOKEN=...

Die erste Anfrage sollte sein:

GET /webadmin/api
Authorization: Bearer <token>
Accept: application/json

Nicht authentifizierte Antwort

GET /webadmin/api ist bewusst öffentlich unbedenklich. Ohne gültiges Bearer-Token liefert er nur minimales Bootstrap-JSON:

  • Produktname
  • API-Version
  • authenticated: false
  • ein Self-Link
  • eine kurze Nachricht, die den Aufrufer zur Authentifizierung auffordert

Er darf kein Endpunkt-Inventar, keine Site-Daten, Content-Verträge, Token-Vorschauen, Token-Hashes, Benutzerdetails, lokalen Pfade oder Server-Interna zurückgeben.

Authentifizierte Antwort

Mit einem gültigen CMS-API-Bearer-Token liefert die Discovery:

  • product: WebBlocks CMS
  • cms_version und product_version
  • api_version
  • authenticated: true
  • die Namen der Token-Capabilities, ohne Token-Wert, Token-Vorschau oder Token-Hash
  • empfohlene nächste Schritte
  • Links für OpenAPI, KI-Leitfaden, Content-Vertrag, Beispiele, Validate/Apply, Seiten, Seitenveröffentlichung, Veröffentlichung seiteneigener Blöcke, Navigation und Shared Slots

Die authentifizierte Antwort ist der kanonische Bootstrap-Vertrag für KI-/Operator-Tools. Tools sollten den zurückgegebenen Links folgen, statt lokalen Dateisystemzugriff auf das CMS-Repository oder die Paketdokumentation anzunehmen.

Für Content-Pläne sind page.path und expected_path kanonische öffentliche Seitenübersetzungs-Pfade wie /contact oder /docs/internal-content-api. /p/... dient nur der öffentlichen Legacy-Kompatibilität und sollte von neuen Tools nicht erzeugt werden.

Verlinkte Ressourcen

Die aktuellen Discovery-Links umfassen:

GET /webadmin/api/openapi.json
GET /webadmin/api/ai-guide
GET /webadmin/api/content-contract
GET /webadmin/api/examples
GET /webadmin/api/examples/contact-page
POST /webadmin/api/content/validate
POST /webadmin/api/content/apply
GET /webadmin/api/pages
GET /webadmin/api/pages/{page}
POST /webadmin/api/pages/{page}/publish
POST /webadmin/api/pages/{page}/publish-page-owned-blocks
GET /webadmin/api/navigation-menus
GET /webadmin/api/shared-slots

Die Content-Validate-/Apply-Links unterstützen sowohl den Planmodus create_draft_page als auch replace_existing_draft_page. Verwenden Sie GET /webadmin/api/content-contract für die aktuelle Modusliste und die Sicherheitsregeln.

Veröffentlichungs-Links erfordern content.publish. POST /webadmin/api/pages/{page}/publish veröffentlicht standardmäßig nur die Seite mit include_page_owned_blocks: false; Entwurfsblöcke werden nicht veröffentlicht, sofern die Anfrage nicht ausdrücklich include_page_owned_blocks: true setzt. Shared-Slot-Kaskadenveröffentlichung wird nicht unterstützt und liefert JSON-Validierungsfeedback. POST /webadmin/api/pages/{page}/publish-page-owned-blocks veröffentlicht geeignete seiteneigene Entwurfs- oder In-Review-Blöcke, ohne den Workflow-Status der Seite zu ändern.

GET /webadmin/api/examples/contact-page demonstriert einen nativen contact_form-Block. Er verzichtet bewusst auf Trusted HTML, rohes Formular-Markup und mailto:-Fallbacks, damit Tools sichere Entwurfs-Kontaktseiten über denselben strukturierten Blockvertrag erstellen können, den Operatoren in der Verwaltung nutzen.

Geschützte Links erfordern:

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

Capabilities

CMS-API-Tokens legen die bei der Token-Erstellung ausgewählten Capabilities in der Discovery offen, damit Tools die erlaubten Aktionen verstehen, bevor sie Schreibvorgänge versuchen.

Standard-Capabilities für den Seitenaufbau:

  • content.read
  • content.validate
  • content.apply
  • navigation.write
  • shared-slots.write

Destruktive oder Veröffentlichungs-Capabilities sind separate erweiterte Optionen und standardmäßig nicht ausgewählt:

  • content.publish
  • pages.delete

Destruktive Operationen müssen eine explizite passende Capability erfordern und sollten normalen Seitenaufbau-Tokens nicht gewährt werden.

Normale Seitenaufbau-Tools sollten nicht davon ausgehen, dass Veröffentlichen verfügbar ist. Fehlt content.publish, sollten Tools vor dem Aufruf der Veröffentlichungs-Endpunkte anhalten und berichten, dass ein vertrauenswürdiges Operator-Token mit Veröffentlichungs-Capability erforderlich ist.

Nur-JSON-Fehler

Die Endpunkte der Content-API liefern JSON-Fehler statt Browser-Weiterleitungen, Login-Seiten oder CSRF-HTML-Antworten. Fehler-Payloads enthalten, wo zutreffend, weiterführende Links:

  • api_discovery_url
  • openapi_url
  • documentation_url
  • example_url

Erwartetes Statusverhalten:

  • 401 bei fehlenden, ungültigen oder widerrufenen Tokens
  • 403 bei fehlenden Capabilities
  • 422 bei ungültigen Content-Payloads

Sicherheit

Discovery-, OpenAPI-, KI-Leitfaden-, Beispiel- und Content-Vertrags-Antworten dürfen keine echten Token-Werte, Token-Hashes, .env-Werte, lokalen Dateisystempfade, Serverpfade, Stacktraces, rohen Exceptions, Datenbank-Interna, Benutzerlisten oder privaten Operator-Details offenlegen.

Vorschau-URLs wie /webadmin/pages/{page}/preview sind Browser-/Admin-Routen. Sie erfordern eine authentifizierte Admin-Browsersitzung und werden nicht mit CMS-API-Bearer-Tokens geöffnet. Eine Login-Weiterleitung von dieser URL bedeutet, dass die Browsersitzung fehlt; es handelt sich nicht um einen Authentifizierungsfehler der internen Content-API.