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.

Inhaltsverzeichnis:

1 1. Unterstützte Methoden
2 2. Schlüssel-Gruppen
3 3. Methoden für Key-Value-Paare
- 3.1 3.1 GET storage/keys
- 3.2 3.2 GET storage/keys/{key}
- 3.3 3.3 POST storage/keys
- 3.4 3.4 DELETE storage/keys/{key}
4 4. Methoden für Schlüssel-Gruppen
- 4.1 4.1 GET storage/groups
- 4.2 4.2 GET storage/groups/{id}
- 4.3 4.3 POST storage/groups
- 4.4 4.4 PUT storage/groups/{id}
- 4.5 4.5 DELETE storage/groups/{id}
5 5. Support

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE

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

2. Schlüssel-Gruppen

Datenfelder einer Schlüssel-Gruppe:

Name	Typ	Verwendung

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"
}

3. 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.

3.1 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], 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

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.

3.2 GET storage/keys/{key}

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

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.

3.3 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

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	"invalidFormat"	`key` enthält Sonderzeichen, die nicht zu `{'_', '-', '/', '.', ':', ' '}` gehören. `key` oder `value` sind leer.
503 Service Unavailable	"internalError"	Der interne `RedisService` kann nicht erreicht werden. Der Wert konnte nicht gespeichert werden.

3.4 DELETE storage/keys/{key}

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

Die Anfrage liefert keine Daten im Response Body zurück, sondern lediglich einen Status-Code.

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:

Es wird nur der Status-Code gesendet.

Fehlercodes:

Fehler	Typ	Grund

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. Der Wert konnte nicht gespeichert werden.

4. 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.

4.1 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

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"	`size` ∉ [1;300] `sort` ∉ {"asc", "desc"} `pageToken` ist keine Zahl oder kleiner als 0.
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 ":".

4.2 GET storage/groups/{id}

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

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.

4.3 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"
}

Fehlercode:

Fehler	Typ	Grund

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	"missing"	`name` oder `keysArray` fehlen.
400 Bad Request	"invalidFormat"	`keysArray` ist kein Array.

4.4 PUT storage/groups/{id}

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

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	"missing"	`id`, `name` oder `keysArray` fehlen.
400 Bad Request	"invalidFormat"	`keysArray` ist kein Array.
503 Service Unavailable	"internalError"	`id` ist ungültig.

4.5 DELETE storage/groups/{id}

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. Der Endpunkt liefert keinen Antwort-Body zurück, sondern nur den Status-Code.

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:

Es wird nur der Status-Code gesendet.

Fehlercode:

Fehler	Typ	Grund

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.

API-Referenz Key-Value-Store

Inhaltsverzeichnis:

1. Unterstützte Methoden

2. Schlüssel-Gruppen

Datenfelder einer Schlüssel-Gruppe:

Beispiel:

3. Methoden für Key-Value-Paare

3.1 GET storage/keys

Beispiel:

Unterstützte Parameter:

Antwort:

Fehlercodes:

3.2 GET storage/keys/{key}

Beispiel:

Antwort:

Fehlercodes:

3.3 POST storage/keys

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.4 DELETE storage/keys/{key}

Beispiel:

Antwort:

Fehlercodes:

4. Methoden für Schlüssel-Gruppen

4.1 GET storage/groups

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes:

4.2 GET storage/groups/{id}

Beispiel:

Antwort:

Fehlercodes:

4.3 POST storage/groups

Beispiel:

Request Body:

Antwort:

Fehlercode:

4.4 PUT storage/groups/{id}

Beispiel:

Request Body:

Antwort:

Fehlercode:

4.5 DELETE storage/groups/{id}

Beispiel:

Antwort:

Fehlercode:

5. Support