Management-API
Die schreibende Schnittstelle für Struktur und Konfiguration: Collections, Blöcke, Layouts, Theme, Seiten, Menüs, Formulare, Medien, Umgebungen und Marketplace – meist über die Kommandozeile hcms genutzt.
Wozu die Management-API?
Über die Management-API ändern Sie die Struktur Ihrer Inhalte als Dateien: Collections, Blöcke, Layouts, Theme, Seiten, Menüs und Formulare. Die Kommandozeile hcms nutzt sie für pull, diff und push (siehe Website als Code). Direkt ansprechen müssen Sie sie selten; diese Seite dient als Referenz.
Basis:
https://<ihre-organisation>.scorebase.ch/headless/api/v1/management
- Jeder Aufruf braucht ein Token mit der Berechtigung Verwaltung (
manage). Ohne sie antwortet die API mit403 FORBIDDEN. - Die Umgebung wählen Sie mit
?environment=<key>; ein an eine Umgebung gebundenes Token nutzt immer seine eigene. - Antworten werden nie zwischengespeichert (
no-store). - Tokens ohne eigenes Limit dürfen hier 60 Anfragen pro Minute stellen.
Endpunkte
| Pfad | Methoden | Zweck ($format) |
hcms-Befehl |
|---|---|---|---|
/management/schema |
GET, PUT | Alle Collections und Feldgruppen (hcms/schema@1) |
hcms schema |
/management/collections |
GET | Alle Collections der Umgebung, auch ohne API aktiv | – |
/management/collections/{slug} |
GET, PUT, DELETE | Eine Collection lesen, anlegen oder ändern; DELETE entfernt die Collection und verschiebt ihre Einträge in den Papierkorb – wie beim Löschen in der Oberfläche | – |
/management/collections/{slug}/revisions |
GET | Versionen einer Collection | – |
/management/blocks |
GET, PUT | Eigene Block-Definitionen (hcms/block@1) |
hcms blocks |
/management/block-components |
GET, PUT | Komponenten (hcms/block-component@1, Schlüssel slug): GET liefert Dateien und stand je Komponente (?stand=veroeffentlicht oder neuester); PUT speichert als Entwurf (?ziel=entwurf, Vorgabe) oder stellt live (?ziel=live), mit dryRun, force und nurAbgleich |
hcms komponenten |
/management/layouts |
GET, PUT | Layouts (hcms/layout@1) |
hcms layouts |
/management/themes |
GET, PUT | Themes (hcms/theme@1, Schlüssel name) |
hcms theme |
/management/pages |
GET, PUT | Seiten mit Block-Baum (hcms/page@1, Schlüssel path und locale) |
hcms pages |
/management/menus |
GET, PUT | Menüs (hcms/menu@1; ein Push ersetzt alle Einträge des Menüs) |
hcms menus |
/management/forms |
GET, PUT | Formulare (hcms/form@1) |
hcms forms |
/management/media |
GET, POST | Medien auflisten; POST lädt eine Datei hoch (multipart/form-data, Felder file und optional folder) |
hcms media |
/management/tokens |
POST | Neues API-Token: { label, environmentKey?, scopes? }, Standard nur Lesen |
hcms analytics setup |
/management/environments |
GET, POST | Umgebungen auflisten, leere Umgebung anlegen | hcms env list |
/management/environments/clone |
POST | Umgebung in eine neue klonen | hcms env clone |
/management/environments/diff |
GET | Zwei Umgebungen vergleichen (?from=&to=&type=schema|content|all) |
– |
/management/environments/promote |
POST | Änderungen in eine bestehende Umgebung übertragen | hcms promote |
/management/operations/{id} |
GET | Stand eines Klon- oder Übertragungsvorgangs | hcms env status |
/management/marketplace/items |
GET | Marketplace-Bausteine auflisten | hcms marketplace add --list |
/management/marketplace/items/{type}/{slug} |
GET | Ein Marketplace-Baustein | – |
/management/marketplace/install |
POST | Baustein in die Umgebung installieren: { type, slug, version? } |
hcms marketplace install |
/management/marketplace/publish |
POST | Eigenen Baustein veröffentlichen | hcms marketplace publish |
Die Editor-Schemas für Komponenten und Blöcke (komponente.schema.json, block.schema.json) liefert GET /editor-schemas (Berechtigung Lesen; mit Verwaltung auch unveröffentlichte Komponenten). hcms types generate schreibt sie neben die Typen.
Einträge schreiben Sie nicht hier, sondern über die Content API (POST …/entries, …/entries/bulk) mit den Berechtigungen Schreiben und Veröffentlichen.
Wie ein Push wirkt
- Idempotent: Abgeglichen wird über den festen Schlüssel der Ressource (
slug,name,keyoderpathmitlocale), nicht über interne IDs. - Ergänzend: Es wird angelegt und aktualisiert, nie gelöscht. Was nur im Ziel existiert, steht in der Antwort unter
removedOnlyReported. - Versioniert: Jeder Push legt eine Version an (Quelle
cli). - Geprüft: Unbekannte Feldtypen, unbekannte Block-Typen in Layouts und Seiten sowie ungültige Dateien ergeben
422 VALIDATION_ERRORmit einer Liste der Fehler. Nicht auflösbare Verweise (z.B. ein Menüeintrag auf eine fehlende Seite) sind nur Warnungen.
Komponenten pushen
PUT /management/block-components nimmt { "komponenten": [ … ] } mit bis zu 4 MB (413 PAYLOAD_TOO_LARGE; laden Sie grössere Mengen in Teilen hoch). Die Antwort nennt created, updated, unchanged, uebersprungen, published, die neuen versionen und die gelaufenen pruefungen.
- Entwurf als Vorgabe: Ohne
zielentsteht ein Entwurf; die Live-Version bleibt. - Versionsschutz: Ist die
versionder Datei älter als die in der App, antwortet der Server mit409 VERSION_CONFLICTunddetails.konflikte(„Gleichzeitig geändert“) und schreibt nichts.?force=trueüberschreibt. - Prüfung: Ungültige Dateien ergeben
422 VALIDATION_ERRORmitdetails.befundeunddetails.pruefungen; es wird nichts gespeichert. Die Management-API legt in der Hike-Umgebung keine Komponenten an (422 KOMPONENTEN_AUS); im Seiten-Editor lassen sie sich einsetzen. - Abgleich:
?dryRun=true&nurAbgleich=truevergleicht nur je Komponente, ob Code oder App neuer ist (so entscheidethcms komponenten pull).
Probelauf
Ein PUT mit ?dryRun=true schreibt nichts und liefert nur, was sich ändern würde:
{ "dryRun": true, "diff": { "…": "…" } }Das entspricht hcms <ressource> push --dry-run bzw. hcms <ressource> diff.
Reihenfolge
Ressourcen verweisen aufeinander. Übernehmen Sie sie in dieser Reihenfolge:
schema → theme → blocks → komponenten → layouts → menus → pages → forms → content
hcms push führt die Stufen bis auf die Einträge in genau dieser Reihenfolge aus; legt pages neue Seiten an, folgt ein zweiter Menü-Push.
Wenn etwas nicht klappt
| Fehler | Ursache | Lösung |
|---|---|---|
403 FORBIDDEN |
Token ohne Verwaltung | Token mit Berechtigung Verwaltung verwenden |
422 VALIDATION_ERROR |
Ungültige Datei, unbekannter Feld- oder Block-Typ | Liste in der Antwort prüfen; Reihenfolge einhalten |
409 VERSION_CONFLICT |
Komponente oder Seite wurde seit dem letzten Pull geändert | Neu ziehen und zusammenführen, oder bewusst ?force=true |
429 RATE_LIMIT_EXCEEDED |
Mehr als 60 Anfragen pro Minute | Retry-After abwarten oder beim Token ein höheres Limit setzen |
| Änderungen landen in der falschen Umgebung | ?environment= fehlt, oder das Token ist gebunden |
Umgebung angeben bzw. passendes Token verwenden |