API-Referenz Key-Value-Store

Der Endpunkt storage/ stellt eine Schnittstelle zur Verfügung, mit der Key-Value-Paare in einem Redis-basierten Speicher verwaltet werden können.

Neben der direkten Speicherung einzelner Schlüssel-Werte-Paare bietet die API die Möglichkeit, diese Einträge zu logischen Gruppen zusammenzufassen, um eine strukturierte Organisation und gezielte Abfragen zu ermöglichen. Unterstützt werden das Erstellen, Abrufen, Aktualisieren und Löschen sowohl einzelner Einträge als auch ganzer Gruppen.

Die API eignet sich insbesondere für temporäre Konfigurationsdaten, Zwischenspeicher oder statusbezogene Informationen im Shop-System.

---

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Key-Value-Paare	storage/keys
Schlüssel-Gruppen	storage/groups

Schlüssel-Gruppen

Datenfelder einer Schlüssel-Gruppe

Name	Typ	Verwendung
createdAt	String	Zeitpunkt der Erstellung (ISO 8601-Format, UTC).
description	String	Beschreibung der Gruppe.
id	Integer	Eindeutige ID der Gruppe.
keysArray	Array	Namen von Schlüsseln, die zu der Gruppe gehören.
name	String	Name der Gruppe.
updatedAt	String	Zeitpunkt der letzten Aktualisierung (ISO 8601-Format, UTC).

Beispiel

{
    "createdAt": "2025-02-17 15:49:33",
    "description": "myDescription",
    "id": 1,
    "keysArray": [
        "asdf",
        "foo"
    ],
    "name": "myGroup",
    "updatedAt": "2025-02-17 15:49:34"
}

Methoden für Key-Value-Paare

Dieser Abschnitt beschreibt die Endpunkte zur Verwaltung einzelner Key-Value-Paare im Key-Value-Store des Systems. Über die API können Einträge erstellt, abgerufen, aktualisiert und gelöscht werden.

Optional kann ein Ablaufdatum (TTL) gesetzt werden, um Werte zeitlich begrenzt zu speichern.

GET storage/keys

Mit diesem Endpunkt wird eine Liste aller im System gespeicherten Key-Value-Paare abgerufen.

Die Werte werden zusammen mit dem zugehörigen Schlüssel (key), dem zugehörigen Wert (value) und einem optionalen Ablaufdatum (expirationDate) ausgegeben. Dieser Endpunkt ermöglicht damit eine Übersicht über alle aktuell vorhandenen Einträge im Key-Value-Store.

Es gibt keine Sortier- und Filterfelder – die Liste der Parameter steht fest. Bei textSearch wird der Name des Schlüssels berücksichtigt, bei filter_contains[value] nicht. filter_contains[value] kann auch mehrfach vorkommen. Andere Parameter funktionieren genauso wie bei Standard-GET-Anfragen.

Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Key-Value-Store-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/storage/keys

Unterstützte Parameter

size, filter_gte[expirationDate], filter_lte[expirationDate], filter_eq[group], pageToken, textSearch, filter_contains[value], sort

Antwort

{
    "endReached": false,
    "items": [
        {
            "expirationDate": "2026-02-18T09:27:09.868Z",
            "key": "asdf",
            "value": "asdf"
        },
        {
            "expirationDate": "2026-02-18T09:24:38.868Z",
            "key": "test",
            "value": "test123"
        }
    ],
    "nextPageToken": "",
    "totalCount": 2
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Key-Value-Store-Daten.
400 Bad Request	”invalidFormat”	Die ID der Gruppe bei filter_eq[group] ist keine positive Ganzzahl. size ist keine positive Ganzzahl.
503 Service Unavailable	”internalError”	Der interne RedisService kann nicht erreicht werden.

GET storage/keys/

Mit diesem Endpunkt kann ein einzelnes Key-Value-Paar anhand seines Schlüssels (key) abgerufen werden.

Die Antwort enthält den gespeicherten Wert (value) sowie optional ein Ablaufdatum (expirationDate), sofern dieses gesetzt wurde.

Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Key-Value-Store-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/storage/keys/asdf

Antwort

{
    "expirationDate": "2025-02-20T15:49:19.169Z",
    "key": "asdf",
    "value": "asdf"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Key-Value-Store-Daten.
400 Bad Request	”invalidFormat”	{key} enthält Sonderzeichen, die nicht zu {'_', '-', '/', '.', ':', ' '} gehören.
400 Bad Request	”missing”	{key} wurde nicht übergeben.
404 Not Found		Der Schlüssel wurde in Redis nicht gefunden.
503 Service Unavailable	”internalError”	Der interne RedisService kann nicht erreicht werden.

POST storage/keys

Mit diesem Endpunkt kann ein neues Key-Value-Paar im Key-Value-Store gespeichert werden.

Der Schlüssel (key) und der zugehörige Wert (value) werden im Request Body übergeben.
Optional kann mit ttlDays eine Lebensdauer in Tagen angegeben werden, nach deren Ablauf der Eintrag automatisch gelöscht wird (TTL = Time To Live).

Wenn das Key-Value-Paar bereits existiert, wird es überschrieben.

Für die Nutzung dieses Endpunkts sind Erstellberechtigungen für Key-Value-Store-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/storage/keys

Request Body

{
    "key": "foo",
    "value": "bar",
    "ttlDays": 2
}

Antwort

{
    "key": "foo",
    "ttl": 172800,
    "ttlDays": 2,
    "value": "bar"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Key-Value-Store-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde im Request Body übergeben.
400 Bad Request	”missing”	key oder value fehlen.
400 Bad Request	”invalidValue”	key oder value sind leer.
400 Bad Request	”invalidFormat”	key enthält Sonderzeichen, die nicht zu {'_', '-', '/', '.', ':', ' '} gehören. key, value oder ttlDays haben einen ungültigen Typ. ttlDays muss eine positive ganze Zahl sein.
503 Service Unavailable	”internalError”	Der interne RedisService kann nicht erreicht werden. Der Wert konnte nicht gespeichert werden.

DELETE storage/keys/

Mit diesem Endpunkt wird ein vorhandenes Key-Value-Paar anhand seines Schlüssels (key) dauerhaft aus dem Key-Value-Store entfernt.

Bei Erfolg wird ein JSON-Objekt mit success: true zurückgegeben.

Für die Nutzung dieses Endpunkts sind Löschberechtigungen für Key-Value-Store-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/storage/keys/asdf

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Key-Value-Store-Daten.
400 Bad Request	”invalidFormat”	{key} enthält Sonderzeichen, die nicht zu {'_', '-', '/', '.', ':', ' '} gehören.
400 Bad Request	”missing”	{key} wurde nicht übergeben.
503 Service Unavailable	”internalError”	Der interne RedisService kann nicht erreicht werden.

Methoden für Schlüssel-Gruppen

Schlüssel-Gruppen dienen der logischen Bündelung mehrerer Key-Value-Paare.
Die hier beschriebenen Endpunkte ermöglichen es, Gruppen anzulegen, zu bearbeiten, abzurufen oder zu löschen. Eine Gruppe enthält Metainformationen wie Name, Beschreibung und eine Liste zugehöriger Schlüssel.

GET storage/groups

Mit diesem Endpunkt wird eine Liste aller im System definierten Schlüssel-Gruppen abgerufen.
Eine Schlüssel-Gruppe ist eine logische Sammlung mehrerer Key-Value-Paare, die unter einem gemeinsamen Gruppennamen verwaltet werden.

Die Antwort enthält u. a. den Namen der Gruppe (name), die Anzahl der enthaltenen Schlüssel (numKeys) sowie Erstell- und Änderungszeitpunkte. Zur Ergebnissteuerung stehen Filter- und Sortierfunktionen zur Verfügung.

Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Key-Value-Store-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/storage/groups/

Antwort

{
    "endReached": true,
    "items": [
        {
            "createdAt": "2025-02-17 15:49:33",
            "description": "",
            "id": 1,
            "keysArray": [
                "asdf"
            ],
            "name": "qwerty",
            "numKeys": 1,
            "updatedAt": "2025-02-17 15:49:34"
        },
        ...
    ],
    "nextPageToken": "MA",
    "totalCount": 1
}

Filterfelder

keysArray

Sortierfelder

numKeys, name, createdAt, updatedAt

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Key-Value-Store-Daten.
400 Bad Request	”invalidValue”
400 Bad Request	”invalidCharacters”	size ist keine Ganzzahl. Ein Filterwert ist ungültig.
400 Bad Request	”unknownDataField”	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	”unknownOperation”	Ein Filtertyp ist ungültig.
400 Bad Request	”syntaxError”	sort enthält mehr als einen oder keinen ”:”.

GET storage/groups/

Mit diesem Endpunkt kann eine einzelne Schlüssel-Gruppe anhand ihrer ID geladen werden.

Die Antwort enthält alle verfügbaren Metadaten zur Gruppe, darunter der Gruppenname (name), eine optionale Beschreibung (description) sowie eine Liste der zugehörigen Schlüssel (keysArray).

Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Key-Value-Store-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/storage/groups/1

Antwort

{
    "createdAt": "2025-02-17 15:49:33",
    "description": "",
    "id": 1,
    "keysArray": [
        "asdf"
    ],
    "name": "qwerty",
    "updatedAt": "2025-02-17 15:49:34"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Key-Value-Store-Daten.
400 Bad Request	”missing”	id wurde nicht übergeben.
503 Service Unavailable	”internalError”	id ist ungültig.
404 Not Found		Die Gruppe mit id={id} wurde nicht gefunden.

POST storage/groups

Mit diesem Endpunkt wird eine neue Schlüssel-Gruppe erstellt.

Eine Schlüssel-Gruppe besteht aus einem eindeutigen Namen (name), einer optionalen Beschreibung (description) und einer Liste von zugeordneten Schlüsseln (keysArray). Die Gruppe kann zur strukturierten Verwaltung und Gruppierung mehrerer Key-Value-Einträge verwendet werden.

Für die Nutzung dieses Endpunkts sind Erstellberechtigungen für Key-Value-Store-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/storage/groups

Request Body

{
    "name": "myGroup",
    "description": "Group description",
    "keysArray": [
        "asdf",
        "foo"
    ]
}

Antwort

{
    "description": "Group description",
    "id": 3,
    "keysArray": [
        "asdf",
        "foo"
    ],
    "name": "myGroup"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Key-Value-Store-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde im Request Body übergeben.
400 Bad Request	”missing”	name oder keysArray fehlen.
400 Bad Request	”invalidValue”	name ist leer.
400 Bad Request	”invalidFormat”	name oder description sind kein String oder keysArray ist kein Array.

PUT storage/groups/

Mit diesem Endpunkt kann eine bestehende Schlüssel-Gruppe anhand ihrer ID aktualisiert werden.

Dabei können der Gruppenname (name), die Beschreibung (description) und die zugehörigen Schlüssel (keysArray) geändert oder neu gesetzt werden.

Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Key-Value-Store-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/storage/groups/1

Request Body

{
    "description": "myDescription",
    "keysArray": [
        "asdf",
        "foo"
    ],
    "name": "qwerty"
}

Antwort

{
    "description": "myDescription",
    "keysArray": [
        "asdf",
        "foo"
    ],
    "name": "qwerty"
}

Fehlercode

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Key-Value-Store-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde im Request Body übergeben.
400 Bad Request	”missing”	id, name oder keysArray fehlen.
400 Bad Request	”invalidValue”	name ist leer.
400 Bad Request	”invalidFormat”	name oder description sind kein String oder keysArray ist kein Array.
503 Service Unavailable	”internalError”	id ist ungültig.

DELETE storage/groups/

Mit diesem Endpunkt wird eine bestehende Schlüssel-Gruppe anhand ihrer ID gelöscht.

Die zugehörigen Key-Value-Einträge bleiben dabei im System erhalten, es wird lediglich die Gruppenzuordnung entfernt. Bei Erfolg wird ein JSON-Objekt mit success: true zurückgegeben.

Für die Nutzung dieses Endpunkts sind Löschberechtigungen für Key-Value-Store-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/storage/groups/1

Antwort

{
    "success": true
}

Fehlercode

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Key-Value-Store-Daten.
400 Bad Request	”missing”	id wurde nicht übergeben.
503 Service Unavailable	”internalError”	id ist ungültig.
404 Not Found		Die Gruppe mit id={id} wurde nicht gefunden.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal

Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.