API reference key-value store - WEBSALE Dokumentation

The storage/ endpoint provides an interface for managing key-value pairs in a Redis-based store. In addition to directly storing individual key-value pairs, the API also offers the option of consolidating these entries into logical groups, enabling structured organization and targeted queries. Creating, retrieving, updating, and deleting both individual entries and entire groups is supported. The API is particularly suitable for temporary configuration data, intermediate caches, or status-related information in the shop system.

Supported methods

List of all supported methods.

Command/info	Endpoints	GET	POST	PUT	DELETE
Key-value pairs	storage/keys
Key groups	storage/groups

Key groups

Data fields of a key group

Name	Type	Usage
createdAt	String	Time of creation (ISO 8601 format, UTC).
description	String	Description of the group.
id	Integer	Unique ID of the group.
keysArray	Array	Names of keys belonging to the group.
name	String	Name of the group.
updatedAt	String	Time of last update (ISO 8601 format, UTC).

Example

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

Methods for key-value pairs

This section describes the endpoints for managing individual key-value pairs in the system’s key-value store. The API can be used to create, retrieve, update, and delete entries. Optionally, an expiration date (TTL) can be set to store values for a limited time.

GET storage/keys

This endpoint retrieves a list of all key-value pairs stored in the system. The values are returned together with the corresponding key (key), the associated value (value), and an optional expiration date (expirationDate). This endpoint thus enables an overview of all entries currently present in the key-value store. There are no sort or filter fields — the list of parameters is fixed. For textSearch, the key name is considered; for filter_contains[value], it is not. filter_contains[value] can also be specified multiple times. Other parameters behave the same as for standard GET requests. Read permissions for key-value store data are required to use this endpoint.

Example

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

Supported parameters

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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read key-value store data.
400 Bad Request	”invalidFormat”	The group ID in `filter_eq[group]` is not a positive integer. `size` is not a positive integer.
503 Service Unavailable	”internalError”	The internal `RedisService` cannot be reached.

GET storage/keys/{key}

This endpoint can be used to retrieve an individual key-value pair by its key (key). The response contains the stored value (value) and, optionally, an expiration date (expirationDate) if one was set. Read permissions for key-value store data are required to use this endpoint.

Example

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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read key-value store data.
400 Bad Request	”invalidFormat”	`{key}` contains special characters that do not belong to `{'_', '-', '/', '.', ':', ' '}`.
400 Bad Request	”missing”	`{key}` was not provided.
404 Not Found		The key was not found in Redis.
503 Service Unavailable	”internalError”	The internal `RedisService` cannot be reached.

POST storage/keys

This endpoint can be used to store a new key-value pair in the key-value store. The key (key) and the associated value (value) are passed in the request body.
Optionally, a lifetime in days can be specified with ttlDays, after which the entry is automatically deleted (TTL = Time To Live). If the key-value pair already exists, it is overwritten. Create permissions for key-value store data are required to use this endpoint.

Example

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

Request body

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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create key-value store data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.
400 Bad Request	”missing”	`key` or `value` is missing.
400 Bad Request	”invalidValue”	`key` or `value` is empty.
400 Bad Request	”invalidFormat”	`key` contains special characters that do not belong to `{'_', '-', '/', '.', ':', ' '}`. `key`, `value`, or `ttlDays` has an invalid type. `ttlDays` must be a positive integer.
503 Service Unavailable	”internalError”	The internal `RedisService` cannot be reached. The value could not be stored.

DELETE storage/keys/{key}

This endpoint permanently removes an existing key-value pair from the key-value store by its key (key). On success, a JSON object with success: true is returned. Delete permissions for key-value store data are required to use this endpoint.

Example

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

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete key-value store data.
400 Bad Request	”invalidFormat”	`{key}` contains special characters that do not belong to `{'_', '-', '/', '.', ':', ' '}`.
400 Bad Request	”missing”	`{key}` was not provided.
503 Service Unavailable	”internalError”	The internal `RedisService` cannot be reached.

Methods for key groups

Key groups are used to logically bundle multiple key-value pairs.
The endpoints described here enable groups to be created, edited, retrieved, or deleted. A group contains meta information such as name, description, and a list of associated keys.

GET storage/groups

This endpoint retrieves a list of all key groups defined in the system.
A key group is a logical collection of multiple key-value pairs that are managed under a shared group name. The response contains, among other things, the group name (name), the number of keys it contains (numKeys), and creation and modification times. Filter and sort functions are available for controlling the results. Read permissions for key-value store data are required to use this endpoint.

Example

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

Response

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

Filter fields

keysArray

Sort fields

numKeys, name, createdAt, updatedAt

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read key-value store data.
400 Bad Request	”invalidValue”
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:”.

GET storage/groups/{id}

This endpoint can be used to load a single key group by its ID. The response contains all available metadata for the group, including the group name (name), an optional description (description), and a list of associated keys (keysArray). Read permissions for key-value store data are required to use this endpoint.

Example

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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read key-value store data.
400 Bad Request	”missing”	`id` was not provided.
503 Service Unavailable	”internalError”	`id` is invalid.
404 Not Found		The group with `id`=`{id}` was not found.

POST storage/groups

This endpoint creates a new key group. A key group consists of a unique name (name), an optional description (description), and a list of assigned keys (keysArray). The group can be used for structured management and grouping of multiple key-value entries. Create permissions for key-value store data are required to use this endpoint.

Example

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

Request body

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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create key-value store data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.
400 Bad Request	”missing”	`name` or `keysArray` is missing.
400 Bad Request	”invalidValue”	`name` is empty.
400 Bad Request	”invalidFormat”	`name` or `description` is not a string, or `keysArray` is not an array.

PUT storage/groups/{id}

This endpoint can be used to update an existing key group by its ID. The group name (name), description (description), and associated keys (keysArray) can be changed or reset. Write permissions for key-value store data are required to use this endpoint.

Example

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

Request body

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

Response

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

Error code

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write key-value store data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.
400 Bad Request	”missing”	`id`, `name`, or `keysArray` is missing.
400 Bad Request	”invalidValue”	`name` is empty.
400 Bad Request	”invalidFormat”	`name` or `description` is not a string, or `keysArray` is not an array.
503 Service Unavailable	”internalError”	`id` is invalid.

DELETE storage/groups/{id}

This endpoint deletes an existing key group by its ID. The associated key-value entries remain in the system; only the group assignment is removed. On success, a JSON object with success: true is returned. Delete permissions for key-value store data are required to use this endpoint.

Example

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

Response

{
    "success": true
}

Error code

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete key-value store data.
400 Bad Request	”missing”	`id` was not provided.
503 Service Unavailable	”internalError”	`id` is invalid.
404 Not Found		The group with `id`=`{id}` was not found.

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.

​Supported methods

​Key groups

​Data fields of a key group

​Example

​Methods for key-value pairs

​GET storage/keys

​Example

​Supported parameters

​Response

​Error codes

​GET storage/keys/{key}

​Example

​Response

​Error codes

​POST storage/keys

​Example

​Request body

​Response

​Error codes

​DELETE storage/keys/{key}

​Example

​Response

​Error codes

​Methods for key groups

​GET storage/groups

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET storage/groups/{id}

​Example

​Response

​Error codes

​POST storage/groups

​Example

​Request body

​Response

​Error codes

​PUT storage/groups/{id}

​Example

​Request body

​Response

​Error code

​DELETE storage/groups/{id}

​Example

​Response

​Error code

​Support

Supported methods

Key groups

Data fields of a key group

Example

Methods for key-value pairs

GET storage/keys

Example

Supported parameters

Response

Error codes

GET storage/keys/{key}

Example

Response

Error codes

POST storage/keys

Example

Request body

Response

Error codes

DELETE storage/keys/{key}

Example

Response

Error codes

Methods for key groups

GET storage/groups

Example

Response

Filter fields

Sort fields

Error codes

GET storage/groups/{id}

Example

Response

Error codes

POST storage/groups

Example

Request body

Response

Error codes

PUT storage/groups/{id}

Example

Request body

Response

Error code

DELETE storage/groups/{id}

Example

Response

Error code

Support