Management-API

Wozu die Management-API?

Die Management-API ist die schreibende Gegenseite zur Delivery-API. Die hcms-CLI ruft sie auf, um code-first Ressourcen zu deployen. In der Regel müssen Sie sie nicht direkt ansprechen – sie ist hier zur Referenz beschrieben.

Basis-Pfad:

https://<slug>.scorebase.ch/headless/api/v1/management

Alle Endpunkte erfordern einen Bearer-Token mit manage-Scope und antworten no-store.

Endpoints

Pfad	Methoden	Zweck / `$format`
`/management/schema`	GET, PUT	Vollständiges Schema (`hcms/schema@1`: Sammlungen + Komponenten)
`/management/blocks`	GET, PUT	Block-Definitionen (`hcms/block@1`)
`/management/layouts`	GET, PUT	Layouts (`hcms/layout@1`)
`/management/themes`	GET, PUT	Theme (`hcms/theme@1`, Upsert über `name`)
`/management/pages`	GET, PUT	Seiten (`hcms/page@1`, Schlüssel `path`+`locale`)
`/management/menus`	GET, PUT	Menüs (`hcms/menu@1`, Push ersetzt alle Einträge)
`/management/forms`	GET, PUT	Formulare
`/management/bookings`	GET, PUT	Buchungen
`/management/shop`	GET, PUT	Webshop (Shop, Produkte, Rabatte)
`/management/tokens`	POST	Token erzeugen (`{ label, environmentKey?, scopes? }`)
`/management/environments`	GET	Environments auflisten
`/management/environments/clone`	POST	Environment klonen
`/management/environments/promote`	POST	Änderungen befördern
`/management/operations/{id}`	GET	Status länger laufender Vorgänge

Push-Semantik

Idempotenter Upsert über den natürlichen Schlüssel jeder Ressource.
Additiv: es wird nie gelöscht; Ressourcen, die nur im Ziel existieren, werden unter removedOnlyReported gemeldet.
Jeder Push schreibt eine Revision (Quelle cli).
Unbekannte Feldtypen führen zu 422 VALIDATION_ERROR mit Liste.

Dry-run

Ein PUT mit ?dryRun=true schreibt nichts und liefert nur den Diff:

{ "dryRun": true, "diff": { /* ... */ } }

Das entspricht hcms <resource> push --dry-run bzw. hcms <resource> diff.

Deploy-Reihenfolge

Der Server erzwingt die Abhängigkeitsreihenfolge. Über die CLI ist das der Ablauf:

schema → blocks → layouts → theme → pages → menus → content

Hinweis: Erzeugen Sie Tokens mit passendem Scope: read fürs Frontend, manage fürs Deployen. Ein Auslieferungs-Token ohne manage erhält bei Management-Aufrufen 403 FORBIDDEN.