API-Referenz Konfiguration
Die Schnittstelle für den Endpunkt config/ ermöglicht den umfassenden Zugriff auf die Shopkonfiguration. Über die REST API lassen sich Konfigurationsdaten abrufen, ändern, löschen oder neu anlegen. Dies umfasst sowohl globale Einstellungen als auch subshopspezifische Überschreibungen.
Die Konfiguration basiert auf vordefinierten Schemas, die bestimmen, welche Daten zulässig sind. Änderungen an Konfigurationsknoten werden serverseitig auf Gültigkeit geprüft. Die REST API erlaubt damit die vollständige Verwaltung der Shopkonfiguration – wie sie auch über das Admin-Interface vorgenommen wird.
Inhaltsverzeichnis:
1. Unterstützte Methoden
Angabe aller unterstützten Methoden.
Befehl/Info | Endpunkte | GET | POST | PUT | DELETE |
|---|---|---|---|---|---|
config/ | |||||
config/nodes/ {selector} | |||||
config/nodes/ {selector}/overwrites |
2. Struktur & Anwendung der Konfiguration über die API
Die Shopkonfiguration ist als gerichteter Graph organisiert. Jeder Knoten in diesem Graphen repräsentiert einen eigenständigen Konfigurationsbereich und kann andere Knoten referenzieren – beispielsweise um eine Sprache oder ein Land anzugeben.
Jeder Konfigurationsknoten hat einen klar definierten Typ, für den ein Schema festlegt, welche Datenfelder erlaubt sind, welche Datentypen sie haben und, ob ein Knoten pro Subshop überschrieben werden darf oder nur einmalig existieren kann. Die Schemata beschreiben damit die Struktur der Konfigurationsdaten, nicht jedoch deren Inhalt.
Die Konfiguration kann vollständig über die REST-API gepflegt werden. Das Admin Interface (AI) ist zusätzlich eine visuelle Darstellung dieser Schnittstelle. Alle Funktionen, die im Interface ausgeführt werden können, stehen auch über die API zur Verfügung – etwa das Erstellen, Anpassen, Löschen oder Überschreiben von Konfigurationsknoten.
Damit eignet sich die API besonders für eine automatisierte Verwaltung der Konfiguration, etwa im Rahmen von:
CI/CD-Prozessen mit klar definierten Konfigurationszuständen,
dem Abgleich von Einstellungen zwischen Test- und Produktivsystemen,
oder der Verwaltung mandantenfähiger Umgebungen mit subshop-spezifischen Varianten.
Die REST-API bietet somit vollständigen Zugriff auf die Konfiguration ihres Shops.
Um die Felder eines Knotens zu ermitteln, muss das zugehörige Schema über den Endpunkt GET config/schemas/{type} geladen werden. Die Struktur dieser Schemata wird im Feld properties beschrieben. Dort sind unter anderem die Felder id, type und optional subtype (z. B. bei type: list) enthalten. id legt fest, wie das Feld heißt, während type und subtype angeben, welche Inhalte erwartet werden. type: object kennzeichnet eine verschachtelte Struktur.
Welche Konfigurationstypen im System verfügbar sind, lässt sich auf zwei Wegen abfragen:
über
GET config/nodeTypes, das eine kompakte Liste aller Typen liefert,oder alternativ über
GET config/schemas, wo zusätzlich das Feldidenthalten ist.
2.1 Gültige {type}- und {selector}-Werte
Die folgenden Tabellen listen die gültigen Werte auf, die bei
GET /api/config/schemas/{type}als{type}undGET /api/config/nodes/{selector}als Top-Level-{selector}
verwendet werden können.
Die Unterknoten, Parameter und Beispiele der einzelnen Bereiche sind nicht Teil dieser API-Referenz. Sie sind vollständig im Dokument Konfiguration beschrieben. Dieser Abschnitt dient ausschließlich als Orientierungs für die gültigen Bezeichner.
3. Methoden für Einstellungen
Dieser Abschnitt beschreibt die verfügbaren REST-Endpunkte zur Verwaltung der Shop-Konfiguration im Admin-Bereich. Über die Schnittstelle können Schemas abgerufen, Konfigurationsknoten analysiert, geprüft, gelöscht oder vollständig zurückgesetzt werden.
Die Konfiguration ist dabei in sogenannte Schemas und Knoten unterteilt, die verschiedenen Bereichen wie Accounts, Aktionen oder Systemfunktionen zugeordnet sind.
Alle Einstellungen gelten entweder global oder subshopspezifisch und können je nach Schema typabhängig angepasst werden.
Die Nutzung der Methoden setzt entsprechende Lese-, Schreib- oder Löschrechte voraus.
3.1 GET config/setup
Mit diesem Endpunkt wird die Setup-Konfiguration pro Subshop und Stage (z. B. work, active) abgerufen.
Die Rückgabe enthält technische Informationen wie die host-, staticDomain- und contentDomain-Werte, die zur Laufzeitkonfiguration und Auslieferung der Inhalte im jeweiligen Subshop benötigt werden. Dieser Endpunkt dient primär der systeminternen oder administrativen Analyse des aktuellen Shop-Setups.
Beispiel:
https://www.<ihr-shop>.de/admin/api/v1/config/setupAntwort:
[
{
"contentDomain": "content.myshop.localhost",
"host": "myshop.localhost",
"id": "deutsch",
"stage": "work",
"staticDomain": "static.myshop.localhost",
"staticUrl": "/static"
},
{
"contentDomain": "content.myshop.localhost",
"host": "myshop.localhost",
"id": "deutsch",
"stage": "active",
"staticDomain": "static.myshop.localhost",
"staticUrl": "/static"
},
{
"contentDomain": "content.myshop.localhost",
"host": "english.localhost",
"id": "english",
"stage": "work",
"staticDomain": "static.myshop.localhost",
"staticUrl": "/static"
},
{
"contentDomain": "content.myshop.localhost",
"host": "english.localhost",
"id": "english",
"stage": "active",
"staticDomain": "static.myshop.localhost",
"staticUrl": "/static"
}
]Fehlercodes:
Fehler | Typ | Grund |
|---|---|---|
401 Unauthorized |
| Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte. |
3.2 GET config/status
Dieser Endpunkt prüft die Konfigurationsdaten auf Unvollständigkeit und Redundanz.
Er meldet, ob Pflichtfelder fehlen oder Knoten mit identischen Daten mehrfach vorhanden sind.
Wird kein Problem erkannt, wird "status": "ok" zurückgegeben.
Die Nutzung erfordert Leseberechtigung für Konfigurationen.
Beispiel:
https://www.<ihr-shop>.de/admin/api/v1/config/statusAntwort:
{
"status": "ok"
}Fehlercodes:
Fehler | Typ | Grund |
|---|---|---|
401 Unauthorized |
| Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Konfigurationen. |
3.3 GET config/schemas
Dieser Endpunkt liefert eine vollständige Liste aller verfügbaren Konfigurationsschemata im System.
Ein Schema beschreibt die Struktur und Eigenschaften eines bestimmten Konfigurationstyps, darunter z. B. Pflichtfelder, Datentypen, Schreibschutz, Überschreibbarkeit pro Subshop oder Singleton-Status.
Die Schemata dienen als technische Grundlage für die Validierung und Bearbeitung von Konfigurationsdaten im Admin Interface oder in automatisierten Prozessen.
Die Nutzung erfordert Leseberechtigungen für Konfigurationsdaten.
Beispiel:
https://www.<ihr-shop>.de/admin/api/v1/config/schemasAntwort:
{
"items": [
{
"id": "accounts.account",
"schema": {
"group": "accounts",
"isCreatable": false,
"isDeletable": false,
"isMainNode": true,
"isSingleton": true,
"isSubshopOverwriteable": true,
"properties": [
{
"id": "login",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"properties": [
{
"default": 5,
"id": "loginBlockCount",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"type": "uint"
},
{
"default": 180,
"id": "loginBlockDuration",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"type": "uint"
},
{
"id": "loginBlockEmail",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"properties": [
{
"id": "template",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"type": "string"
},
{
"id": "subject",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"type": "string"
},
...
],
"type": "object"
},
{
"default": false,
"id": "ipBlockEnabled",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"type": "bool"
},
{
"default": 10,
"id": "ipBlockCount",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"type": "uint"
},
{
"default": 1,
"id": "ipBlockCountDuration",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"type": "uint"
},
{
"default": 10,
"id": "ipBlockDuration",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"type": "uint"
}
],
"type": "object"
},
{
"id": "passwordChecks",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"type": "multiService"
},
...
],
"type": "account"
},
"type": "account",
"updatedAt": "2025-04-28T10:24:13.000Z"
},
...
]
}Fehlercodes:
Fehler | Typ | Grund |
|---|---|---|
401 Unauthorized |
| Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Konfigurationen. |
3.4 GET config/schemas/{type}
Mit diesem Endpunkt kann das Schema eines bestimmten Konfigurationstyps abgerufen werden.
Das Schema definiert die zulässigen Felder, deren Datentypen, optionale und Pflichtangaben sowie administrative Eigenschaften wie Schreibschutz, Löschbarkeit oder Subshop-Überschreibbarkeit.
Die Informationen dienen dem Admin Interface und anderen Tools zur strukturellen Validierung und Darstellung von Konfigurationseinträgen im System.
Leserechte für Konfigurationsdaten sind erforderlich.
Beispiel:
https://www.<ihr-shop>.de/admin/api/v1/config/schemas/general.salutationAntwort:
{
"group": "general",
"isCreatable": false,
"isDeletable": false,
"isMainNode": true,
"isSingleton": true,
"isSubshopOverwriteable": true,
"properties": [
{
"id": "codeList",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"properties": [
{
"id": "code",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"type": "string"
},
{
"id": "text",
"isOptional": false,
"isReadOnly": false,
"isUnique": false,
"type": "string"
}
],
"subtype": "object",
"type": "list"
}
],
"type": "salutation"
}Fehler | Typ | Grund |
|---|---|---|
401 Unauthorized |
| Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Konfigurationen. |
404 Not Found | "schema not found" | Das Schema wurde nicht gefunden. |
3.5 GET config/nodeTypes
Dieser Endpunkt liefert eine Übersicht über alle im System vorhandenen Konfigurationsknotentypen, gruppiert nach Schema.
Für jeden Typ wird die Anzahl der erfassten Knoten zurückgegeben – also wie viele Konfigurationseinträge zu einem bestimmten Typ aktuell existieren. Die Information eignet sich beispielsweise zur Bestandsaufnahme, zur Validierung der Konfigurationsstruktur oder als Grundlage für die dynamische Darstellung im Admin Interface.
Zum Abruf sind Leseberechtigungen für Konfigurationen erforderlich.
Beispiel:
https://www.<ihr-shop>.de/admin/api/v1/config/nodeTypesAntwort:
[
{
"count": 1,
"type": "accounts.account"
},
{
"count": 1,
"type": "accounts.accountRestrictions"
},
{
"count": 1,
"type": "accounts.addressField"
},
{
"count": 0,
"type": "accounts.addressFieldsSettings"
},
{
"count": 0,
"type": "accounts.bankInfoField"
},
{
"count": 0,
"type": "accounts.creditCardField"
},
{
"count": 0,
"type": "accounts.customAddressField"
},
{
"count": 1,
"type": "actions.accountDelete"
},
{
"count": 1,
"type": "actions.accountRegister"
},
{
"count": 1,
"type": "actions.addressCreate"
},
{
"count": 1,
"type": "actions.addressDelete"
},
{
"count": 1,
"type": "actions.addressUpdate"
},
{
"count": 1,
"type": "actions.basketItemAdd"
},
{
"count": 1,
"type": "actions.basketItemDelete"
},
...
]Fehlercodes:
Fehler | Typ | Grund |
|---|---|---|
401 Unauthorized |
| Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Konfigurationen. |
4. Methoden für die Verwaltung von Knoten im Shop
Über diese Methoden können Konfigurationsknoten im Shop ausgelesen, erstellt, aktualisiert oder gelöscht werden. Dabei handelt es sich um konkrete Instanzen von Einstellungen, die im Admin-Bereich des Shops gepflegt werden – z. B. für das Verhalten beim Account-Login oder für Einwilligungsdienste wie Cookie-Services.
Je nach Typ des zugrunde liegenden Schemas kann ein Konfigurationsknoten entweder:
als Singleton definiert sein – d. h. es darf nur ein einziger Knoten dieses Typs im Shop existieren (z. B. ein globaler Login-Knoten),
oder als Multiknoten – bei dem mehrere Knoten desselben Typs erlaubt sind (z. B. mehrere Cookie-Services unter
general.consentCookieService).
Die Gültigkeit der Daten wird beim Anlegen oder Aktualisieren anhand des zugehörigen Schemas geprüft.
Die Zugriffe setzen entsprechende Berechtigungen zum Lesen, Schreiben oder Löschen von Konfigurationen voraus.
4.1 GET config/nodes/{selector}
Mit dieser Methode wird die Konfiguration eines oder mehrerer Knoten basierend auf dem angegebenen selector geladen. Der selector setzt sich in der Regel aus dem Schema und dem Knotentyp zusammen (z. B. actions.guestRegister oder general.consentCookieService).
Abhängig vom Knoten liefert der Endpunkt entweder ein einzelnes Konfigurationselement oder eine Liste von Elementen.
Die Antwort enthält jeweils die Konfigurationsdaten sowie Metainformationen wie id, type, label und updatedAt.
Die Lese-Berechtigung für Konfigurationsdaten ist erforderlich.
Beispiel 1:
https://www.<ihr-shop>.de/admin/api/v1/config/nodes/actions.guestRegisterAntwort 1:
{
"items": [
{
"data": {
"errorCodes": {
"createError": "Fehler beim Anlegen des Accounts",
"duplicateEmail": "Für die E-Mail existiert bereits ein Account",
"missingEmail": "E-Mail fehlt",
"missingPassword": "Passwort fehlt",
"nonGuestAccount": "Kein Gast-Account",
"passwordCheckFailed": "Passwort ungenügend",
"passwordMismatch": "Passwörter stimmen nicht überein"
},
"restrictions": {
"autoLoginAllowed": true
},
"verifyEmail": {
"fromAddress": "noreply@websale.de",
"fromName": "Mein Onlineshop",
"subject": "Mein Onlineshop | Registrierung",
"template": "accountRegister.htm"
}
},
"id": "actions.guestRegister",
"label": "guestRegister",
"type": "guestRegister",
"updatedAt": "2025-02-17 14:24:08"
}
]
}Beispiel 2:
https://www.<ihr-shop>.de/admin/api/v1/config/nodes/general.consentCookieServiceAntwort 2:
{
"endReached": true,
"items": [
{
"data": {
"description": "",
"label": "Google Analytics",
"name": "google",
"service": {
"externalService": {},
"shopService": null
}
},
"id": "general.consentCookieService.googleAnalytics",
"label": "consentCookieService",
"type": "consentCookieService",
"updatedAt": "2025-02-17 14:24:18"
},
...
],
"nextPageToken": "MA",
"totalCount": 21
}Fehlercodes:
Fehler | Typ | Grund |
|---|---|---|
401 Unauthorized |
| Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Konfigurationen. |
400 Bad Request | "invalidSelector" |
Die Konfiguration wurde nicht gefunden. |
4.2 PUT config/nodes/{selector}
Diese Methode dient zum Aktualisieren eines Konfigurationsknotens anhand seines Selectors. Der übergebene Dateninhalt wird dabei automatisch gegen das hinterlegte Schema geprüft. Wird das Schema verletzt, erfolgt eine detaillierte Fehlermeldung.
Der Selector besteht aus zwei oder drei durch Punkte getrennten Teilen (z. B. actions.guestRegister oder general.consentCookieService.googleAnalytics). Das Format muss korrekt sein, damit die Konfiguration eindeutig zugeordnet werden kann.
Wenn die Validierung Fehlgeschlagen ist, enthält die Antwort Hinweise in Textform. Zum Beispiel: “The value of the field 'name' has the wrong type. Expected: string.”. Fehler sind auch im Feld errors aufgelistet.
Mögliche Fehlertypen (error.error):
0 = WrongType1 = WrongEnumValue2 = KeyNotAllowed3 = IsReadOnly4 = NotUnique5 = InvalidSelfAssociation
Schreibberechtigungen für Konfigurationen sind erforderlich.
Beispiel:
https://www.<ihr-shop>.de/admin/api/v1/config/nodes/actions.guestRegisterRequest Body:
{
"data": {
"errorCodes": {
"createError": "Fehler beim Anlegen des Accounts",
"duplicateEmail": "Für die E-Mail existiert bereits ein Account",
"missingEmail": "E-Mail fehlt",
"missingPassword": "Passwort fehlt",
"nonGuestAccount": "Kein Gast-Account",
"passwordCheckFailed": "Passwort ungenügend",
"passwordMismatch": "Passwörter stimmen nicht überein"
},
"restrictions": {
"autoLoginAllowed": true
},
"verifyEmail": {
"fromAddress": "noreply@websale.de",
"fromName": "Mein Onlineshop",
"subject": "Mein Onlineshop | Registrierung",
"template": "accountRegister.htm"
}
}
}Antwort:
{
"data": {
<data from the request body>
},
"id": "actions.guestRegister",
"label": "guestRegister",
"type": "guestRegister",
"updatedAt": "2025-02-17 14:24:08"
}Antwort wenn die Validierung Fehlgeschlagen ist:
{
"detail": "The value of the field 'name' has the wrong type. Expected: string. The value of the field 'service.externalService' has the wrong type. Expected: object.",
"error": "dataNotCorrect",
"errors": [
{
"error": {
"error": 0,
"expectedDataType": "string"
},
"field": "name"
},
{
"error": {
"error": 0,
"expectedDataType": "object"
},
"field": "service.externalService"
}
]
}Fehlercodes:
Fehler | Typ | Grund |
|---|---|---|
401 Unauthorized |
| Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Konfigurationen. |
400 Bad Request |
| Request body konnte nicht geladen werden. |
400 Bad Request | "invalidSelector" |
|
400 Bad Request | "dataMissing" |
|
400 Bad Request | "dataNotCorrect" | Daten entsprechen dem Schema nicht. Es wird ein Kommentar geliefert, wo steht, was genau nicht stimmt. |
400 Bad Request | "updateFailed" | Das Aktualisieren ist fehlgeschlagen. |
400 Bad Request | "NodeNotFound" | Die Konfiguration wurde nicht gefunden. |
404 Not Found | "NodeNotFound" | Die Konfiguration wurde nicht gefunden. |
503 Service Unavailable | "internalError" | Sonstiger Fehler. Details sind in Logs zu finden. |
4.3 POST config/nodes/{selector}
Ein Konfigurationsknoten wird erstellt, dabei wird die Schema-Gültigkeit geprüft.
Diese Methode legt einen neuen Konfigurationsknoten innerhalb des angegebenen Schemas an. Dabei wird geprüft, ob der Knoten gemäß Schema erstellt werden darf (z. B. nicht bei Singleton-Schemata) und ob die übergebenen Daten gültig sind. Die Struktur muss dem Schema entsprechen, sonst wird der Vorgang mit einer präzisen Fehlermeldung abgelehnt.
Der selector besteht immer aus zwei durch Punkt getrennten Teilen (z. B. general.consentCookieService), die den Schema-Typ beschreiben. Zusätzlich muss im Request-Body ein eindeutiges id-Feld angegeben werden, das an den Selector angehängt wird (z. B. test → ergibt general.consentCookieService.test).
Wenn die Validierung Fehlgeschlagen ist, enthält die Antwort Hinweise in Textform. Zum Beispiel: “The value of the field 'name' has the wrong type. Expected: string.”. Fehler sind auch im Feld errors aufgelistet.
Mögliche Fehlertypen (error.error):
0 = WrongType1 = WrongEnumValue2 = KeyNotAllowed3 = IsReadOnly4 = NotUnique5 = InvalidSelfAssociation
Erstellrechte für Konfigurationen sind erforderlich.
Beispiel:
https://www.<ihr-shop>.de/admin/api/v1/config/nodes/general.consentCookieServiceRequest Body:
{
"data": {
"description": "",
"label": "Econda Analytics",
"name": "econda",
"service": {
"externalService": {},
"shopService": null
}
},
"id": "test"
}Antwort:
{
"data": {
"description": "",
"label": "Econda Analytics",
"name": "econda",
"service": {
"externalService": {},
"shopService": null
}
},
"id": "general.consentCookieService.test",
"label": "consentCookieService",
"type": "consentCookieService",
"updatedAt": ""
}Antwort wenn die Validierung Fehlgeschlagen ist:
{
"detail": "The value of the field 'name' has the wrong type. Expected: string. The value of the field 'service.externalService' has the wrong type. Expected: object.",
"error": "dataNotCorrect",
"errors": [
{
"error": {
"error": 0,
"expectedDataType": "string"
},
"field": "name"
},
{
"error": {
"error": 0,
"expectedDataType": "object"
},
"field": "service.externalService"
}
]
}Fehlercodes:
Fehler | Typ | Grund |
|---|---|---|
401 Unauthorized |
| Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Konfigurationen. |
400 Bad Request |
| Request body konnte nicht geladen werden. |
400 Bad Request | "invalidSelector" |
|
400 Bad Request | "typeInvalid" | Es gibt kein Schema mit dem Typ des Konfigurationsknotens. |
400 Bad Request |
© 2025 WEBSALE AG | Impressum | Datenschutz