Skip to content

CC-40120 Glossary Backend API. #3901

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
spryker-release-bot merged 1 commit into from
Sep 15, 2026
Merged

CC-40120 Glossary Backend API. #3901

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions _data/sidebars/pbc_all_sidebar.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1751,6 +1751,15 @@ entries:
- title: Add push notification subscriptions
url: /docs/pbc/all/miscellaneous/manage-using-glue-api/glue-api-add-push-notification-subscriptions.html

- title: Manage glossary keys via Backend API
nested:
- title: Retrieve glossary keys
url: /docs/pbc/all/miscellaneous/manage-using-backend-api/glossary-keys/backend-api-retrieve-glossary-keys.html
- title: Create a glossary key
url: /docs/pbc/all/miscellaneous/manage-using-backend-api/glossary-keys/backend-api-create-a-glossary-key.html
- title: Update translations of a glossary key
url: /docs/pbc/all/miscellaneous/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.html

- title: Third-party integrations
nested:
- title: Customer service
Expand Down
6 changes: 6 additions & 0 deletions ...des/pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
| ATTRIBUTE | TYPE | DESCRIPTION |
| --- | --- | --- |
| key | String | Unique key of the glossary entry. It is also the resource `id`. |
| translations | Array | Translations of the key, one entry per configured locale, ordered by `localeName`. The list is always complete: a locale without an active translation is included with `value: null`. |
| translations.localeName | String | Locale name—for example, `en_US`. |
| translations.value | String | Translated text in the locale. `null` when the key has no active translation in the locale. |
127 changes: 127 additions & 0 deletions ...est/manage-using-backend-api/glossary-keys/backend-api-create-a-glossary-key.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
---
title: "Backend API: Create a glossary key"
description: Learn how to create glossary keys with translations in one or several locales using the Spryker Backend API.
last_updated: Sep 9, 2026
template: default
related:
- title: Authenticate as a Back Office user
link: docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html
- title: Retrieve glossary keys
link: docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-retrieve-glossary-keys.html
- title: Update translations of a glossary key
link: docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.html
- title: Add translations in the Back Office
link: docs/pbc/all/miscellaneous/latest/manage-in-the-back-office/add-translations.html
---

The `glossary-keys` resource of the Backend API lets Back Office integrations create glossary keys together with their translations. This document describes how to create a glossary key and which validations the request has to pass.

## Installation

The endpoints are provided by the `Glossary` module. For details on installing it, see [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html).

## Create a glossary key

To create a glossary key, send the request:

---
`POST` **/glossary-keys**

---

### Request

| HEADER KEY | HEADER VALUE | REQUIRED | DESCRIPTION |
| --- | --- | --- | --- |
| Authorization | string | ✓ | Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by [authenticating as a Back Office user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html). |

Request sample: create a glossary key with translations in two locales

`POST https://glue-backend.mysprykershop.com/glossary-keys`

```json
{
"data": {
"type": "glossary-keys",
"attributes": {
"key": "general.newsletter.hint",
"translations": [
{
"localeName": "en_US",
"value": "Subscribe to our newsletter"
},
{
"localeName": "de_DE",
"value": "Abonnieren Sie unseren Newsletter"
}
]
}
}
}
```

| ATTRIBUTE | TYPE | REQUIRED | DESCRIPTION |
| --- | --- | --- | --- |
| key | String | ✓ | Unique glossary key, up to 255 characters. It becomes the resource `id` and cannot be changed later. Keys are matched case-insensitively, so a key that differs from an existing one only by case is rejected as a duplicate. |
| translations | Array | | Translations of the key. Provide any subset of the configured locales; each `localeName` can appear once. Omit the attribute or send an empty array to create the key without translations. |
| translations.localeName | String | ✓ | Name of a configured locale—for example, `en_US`. |
| translations.value | String | ✓ | Translated text in the locale. Must be a non-empty string. |

{% info_block infoBox "Locales without a translation" %}

You can create a key with translations in a subset of the configured locales. The locales you omit are returned with `value: null`, and the key is not translated in those locales until you [add the translations](/docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.html).

{% endinfo_block %}

### Response

The response contains the created glossary key with one `translations` entry per configured locale.

<details>
<summary>Response sample: create a glossary key</summary>

```json
{
"data": {
"id": "general.newsletter.hint",
"type": "glossary-keys",
"attributes": {
"key": "general.newsletter.hint",
"translations": [
{
"localeName": "de_DE",
"value": "Abonnieren Sie unseren Newsletter"
},
{
"localeName": "en_US",
"value": "Subscribe to our newsletter"
}
]
},
"links": {
"self": "https://glue-backend.mysprykershop.com/glossary-keys/general.newsletter.hint"
}
}
}
```

</details>

{% include /pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md %} <!-- To edit, see _includes/pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md -->

## Possible errors

The request is validated as a whole: if any check fails, nothing is created and all failed checks are returned in the `errors` array.

| STATUS | CODE | REASON |
| --- | --- | --- |
| 422 | 901 | A required attribute is missing, is blank, or has a wrong type—for example, `key => This value should not be blank.` or `translations.0.value => This value should not be blank.` |
| 422 | N/A | A glossary key with the specified `key` already exists. Keys are compared case-insensitively. |
| 422 | N/A | A locale specified in `translations` is not configured, or an entry has no `localeName`. |
| 422 | N/A | A `localeName` appears more than once in `translations`. |
| 422 | N/A | A `value` in `translations` is `null`. When creating a key, every listed locale needs a translated text; to create the key without a translation in a locale, omit that locale. |

| 401 | N/A | The `Authorization` header is missing, or the access token is invalid or expired. |
| 403 | N/A | The authenticated Back Office user is not allowed to access the `glossary-keys` resource. |

To view generic errors and status codes of the Backend API, see [Backend API request and response reference](/docs/integrations/spryker-api/backend-api/developing-apis/backend-api-request-and-response-reference.html#http-status-codes).
205 changes: 205 additions & 0 deletions ...st/manage-using-backend-api/glossary-keys/backend-api-retrieve-glossary-keys.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
---
title: "Backend API: Retrieve glossary keys"
description: Learn how to retrieve the glossary key collection and single glossary keys with their translations, and how to paginate, sort, and filter them using the Spryker Backend API.
last_updated: Sep 9, 2026
template: default
related:
- title: Authenticate as a Back Office user
link: docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html
- title: Create a glossary key
link: docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-create-a-glossary-key.html
- title: Update translations of a glossary key
link: docs/pbc/all/miscellaneous/latest/manage-using-backend-api/glossary-keys/backend-api-update-translations-of-a-glossary-key.html
- title: Manage translations in the Back Office
link: docs/pbc/all/miscellaneous/latest/manage-in-the-back-office/manage-translations-in-the-back-office.html
---

The `glossary-keys` resource of the Backend API lets Back Office integrations read glossary keys and their translations. This document describes how to retrieve a paginated glossary key collection and a single glossary key.

## Installation

The endpoints are provided by the `Glossary` module. For details on installing it, see [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html).

## Retrieve glossary keys

To retrieve a paginated collection of glossary keys, send the request:

---
`GET` **/glossary-keys**

---

### Request

| HEADER KEY | HEADER VALUE | REQUIRED | DESCRIPTION |
| --- | --- | --- | --- |
| Authorization | string | &check; | Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by [authenticating as a Back Office user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html). |

| QUERY PARAMETER | DESCRIPTION | EXEMPLARY VALUES |
| --- | --- | --- |
| page[limit] | Number of glossary keys per page. Default: `10`, maximum: `100`. A higher value is reduced to the maximum. | `page[limit]=20` |
| page[offset] | Number of glossary keys to skip. Default: `0`. | `page[offset]=20` |
| sort | Sorts the collection by a field. Prefix the field with `-` for descending order. The only supported field is `key`; the collection is sorted by `key` in ascending order by default. Any other field returns a `400` error. | `sort=key`<br>`sort=-key` |
| filter[glossary-keys.key] | Returns only the glossary keys that contain the specified fragment. The fragment is matched case-insensitively. | `filter[glossary-keys.key]=general.` |
| filter[glossary-keys.value] | Returns only the glossary keys that have at least one active translation, in any locale, containing the specified fragment. The fragment is matched case-insensitively. Removed translations are not matched. | `filter[glossary-keys.value]=Weiter` |

When both filters are provided, a glossary key has to match both of them.

| REQUEST | USAGE |
| --- | --- |
| `GET https://glue-backend.mysprykershop.com/glossary-keys` | Retrieve the first page of the glossary key collection. |
| `GET https://glue-backend.mysprykershop.com/glossary-keys?page[limit]=2&page[offset]=2` | Retrieve the second page of the collection with two glossary keys per page. |
| `GET https://glue-backend.mysprykershop.com/glossary-keys?sort=-key` | Retrieve glossary keys sorted by key in descending order. |
| `GET https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=general.` | Retrieve glossary keys containing `general.`. |
| `GET https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.value]=Weiter` | Retrieve glossary keys with an active translation containing `Weiter` in any locale. |
| `GET https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=button&filter[glossary-keys.value]=Next` | Retrieve glossary keys containing `button` that have an active translation containing `Next`. |

### Response

The pagination summary is returned in the top-level `meta.pagination` object, and the pagination links in the top-level `links` object. Collection members do not carry pagination data.

Every glossary key carries one `translations` entry per configured locale, even when a filter matched the key by one of its translations only.

<details>
<summary>Response sample: retrieve glossary keys</summary>

```json
{
"links": {
"self": "https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=general.",
"first": "https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=general.&page[limit]=2&page[offset]=0",
"last": "https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=general.&page[limit]=2&page[offset]=60",
"next": "https://glue-backend.mysprykershop.com/glossary-keys?filter[glossary-keys.key]=general.&page[limit]=2&page[offset]=2"
},
"meta": {
"pagination": {
"numFound": 61,
"currentPage": 1,
"maxPage": 31,
"currentItemsPerPage": 2
}
},
"data": [
{
"id": "general.back",
"type": "glossary-keys",
"attributes": {
"key": "general.back",
"translations": [
{
"localeName": "de_DE",
"value": "Zurück"
},
{
"localeName": "en_US",
"value": "Back"
}
]
},
"links": {
"self": "https://glue-backend.mysprykershop.com/glossary-keys/general.back"
}
},
{
"id": "general.next.button",
"type": "glossary-keys",
"attributes": {
"key": "general.next.button",
"translations": [
{
"localeName": "de_DE",
"value": "Weiter"
},
{
"localeName": "en_US",
"value": "Next"
}
]
},
"links": {
"self": "https://glue-backend.mysprykershop.com/glossary-keys/general.next.button"
}
}
]
}
```

</details>

| META ATTRIBUTE | TYPE | DESCRIPTION |
| --- | --- | --- |
| pagination.numFound | Integer | Total number of glossary keys in the collection. |
| pagination.currentPage | Integer | Number of the current page. |
| pagination.maxPage | Integer | Total number of pages. |
| pagination.currentItemsPerPage | Integer | Number of glossary keys per page. |

{% include /pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md %} <!-- To edit, see _includes/pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md -->

## Retrieve a glossary key

To retrieve a single glossary key with its translations, send the request:

---
`GET` **/glossary-keys/*{% raw %}{{key}}{% endraw %}***

---

| PATH PARAMETER | DESCRIPTION |
| --- | --- |
| {% raw %}***{{key}}***{% endraw %} | Glossary key to retrieve. The key is matched case-insensitively; the response contains the stored key. To get it, [retrieve glossary keys](#retrieve-glossary-keys). |

### Request

| HEADER KEY | HEADER VALUE | REQUIRED | DESCRIPTION |
| --- | --- | --- | --- |
| Authorization | string | &check; | Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by [authenticating as a Back Office user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html). |

Request sample: retrieve a glossary key

`GET https://glue-backend.mysprykershop.com/glossary-keys/general.next.button`

### Response

<details>
<summary>Response sample: retrieve a glossary key</summary>

```json
{
"data": {
"id": "general.next.button",
"type": "glossary-keys",
"attributes": {
"key": "general.next.button",
"translations": [
{
"localeName": "de_DE",
"value": "Weiter"
},
{
"localeName": "en_US",
"value": "Next"
}
]
},
"links": {
"self": "https://glue-backend.mysprykershop.com/glossary-keys/general.next.button"
}
}
}
```

</details>

{% include /pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md %} <!-- To edit, see _includes/pbc/all/glue-api-guides/latest/glossary-keys-backend-response-attributes.md -->

## Possible errors

| STATUS | CODE | REASON |
| --- | --- | --- |
| 400 | 400 | The `sort` parameter references an unsupported field. The supported fields are listed in the error details. |
| 404 | N/A | The glossary key with the specified key doesn't exist. |

| 401 | N/A | The `Authorization` header is missing, or the access token is invalid or expired. |
| 403 | N/A | The authenticated Back Office user is not allowed to access the `glossary-keys` resource. |

To view generic errors and status codes of the Backend API, see [Backend API request and response reference](/docs/integrations/spryker-api/backend-api/developing-apis/backend-api-request-and-response-reference.html#http-status-codes).
Loading
Loading