Backend API: Retrieve categories

Last updated:
Edit on GitHub

The categories resource of the Backend API lets Back Office integrations read the category tree of the shop. This document describes how to retrieve a paginated category collection and a single category by its key.

Installation

The endpoints are provided by the Category and ProductCategory modules. For details on installing the category capability, see Install the Category Management feature.

Retrieve categories

To retrieve a paginated collection of categories, send the request:

GET /categories

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.
QUERY PARAMETER DESCRIPTION EXEMPLARY VALUES
page[limit] Number of categories per page. Default: 10. page[limit]=20
page[offset] Number of categories to skip. Default: 0. page[offset]=20
sort Sorts the collection by a field. Prefix the field with - for descending order. Supported fields: categoryKey, position, name. name sorts by the localized name in the request locale, which you pass in the Accept-Language header; if the header is missing, the default locale is used. Categories without a name in that locale are not part of a name-sorted result. Any other field returns a 400 error. sort=name
sort=-position
parentCategoryKey Returns only the direct children of the category with the specified key, including the categories that have it as an additional parent. The key is matched case-insensitively. An unknown key returns a 404 error. parentCategoryKey=computer
REQUEST USAGE
GET https://glue-backend.mysprykershop.com/categories Retrieve the first page of the category collection.
GET https://glue-backend.mysprykershop.com/categories?page[limit]=2&page[offset]=2 Retrieve the second page of the collection with two categories per page.
GET https://glue-backend.mysprykershop.com/categories?sort=-name Retrieve categories sorted by their localized name in descending order.
GET https://glue-backend.mysprykershop.com/categories?parentCategoryKey=computer&sort=position Retrieve the direct child categories of the computer category ordered as in the Back Office category tree.

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.

Response sample: retrieve categories 
{
    "links": {
        "self": "https://glue-backend.mysprykershop.com/categories",
        "first": "https://glue-backend.mysprykershop.com/categories?page[limit]=2&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/categories?page[limit]=2&page[offset]=32",
        "prev": "https://glue-backend.mysprykershop.com/categories?page[limit]=2&page[offset]=0",
        "next": "https://glue-backend.mysprykershop.com/categories?page[limit]=2&page[offset]=4"
    },
    "meta": {
        "pagination": {
            "numFound": 34,
            "currentPage": 2,
            "maxPage": 17,
            "currentItemsPerPage": 2
        }
    },
    "data": [
        {
            "id": "camcorders",
            "type": "categories",
            "attributes": {
                "categoryKey": "camcorders",
                "isActive": true,
                "isInMenu": true,
                "isSearchable": true,
                "isClickable": true,
                "templateName": "Catalog (default)",
                "parentCategoryKey": "cameras-and-camcorder",
                "position": 90,
                "extraParentCategoryKeys": [],
                "localizedAttributes": [
                    {
                        "localeName": "de_DE",
                        "name": "Digitale Videokameras",
                        "metaTitle": "Digitale Videokameras",
                        "metaDescription": "Digitale Videokameras",
                        "metaKeywords": "Digitale Videokameras",
                        "url": "/de/kameras-&-camcorders/digitale-videokameras"
                    },
                    {
                        "localeName": "en_US",
                        "name": "Camcorders",
                        "metaTitle": "Camcorders",
                        "metaDescription": "Camcorders",
                        "metaKeywords": "Camcorders",
                        "url": "/en/cameras-&-camcorders/camcorders"
                    }
                ],
                "stores": [
                    "DE",
                    "AT"
                ],
                "imageSets": [],
                "isRoot": false
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/categories/camcorders"
            }
        },
        {
            "id": "digital-cameras",
            "type": "categories",
            "attributes": {
                "categoryKey": "digital-cameras",
                "isActive": true,
                "isInMenu": true,
                "isSearchable": true,
                "isClickable": true,
                "templateName": "Catalog (default)",
                "parentCategoryKey": "cameras-and-camcorder",
                "position": 100,
                "extraParentCategoryKeys": [],
                "localizedAttributes": [
                    {
                        "localeName": "de_DE",
                        "name": "Digitale Kameras",
                        "metaTitle": "Digitale Kameras",
                        "metaDescription": "Digitale Kameras",
                        "metaKeywords": "Digitale Kameras",
                        "url": "/de/kameras-&-camcorders/digitale-kameras"
                    },
                    {
                        "localeName": "en_US",
                        "name": "Digital Cameras",
                        "metaTitle": "Digital Cameras",
                        "metaDescription": "Digital Cameras",
                        "metaKeywords": "Digital Cameras",
                        "url": "/en/cameras-&-camcorders/digital-cameras"
                    }
                ],
                "stores": [
                    "DE",
                    "AT"
                ],
                "imageSets": [],
                "isRoot": false
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/categories/digital-cameras"
            }
        }
    ]
}
META ATTRIBUTE TYPE DESCRIPTION
pagination.numFound Integer Total number of categories in the collection.
pagination.currentPage Integer Number of the current page.
pagination.maxPage Integer Total number of pages.
pagination.currentItemsPerPage Integer Number of categories per page.
ATTRIBUTE TYPE DESCRIPTION
categoryKey String Unique key of the category. It is also the resource id.
uuid String Universally unique identifier of the category. Read-only. It is null on installations that do not have the optional uuid column, and on categories created before it was introduced until uuid:generate Category spy_category has been run for them. categoryKey, not uuid, is the resource id.
isActive Boolean Defines whether the category is active.
isInMenu Boolean Defines whether the category is shown in the Storefront navigation menu.
isSearchable Boolean Defines whether the category is searchable.
isClickable Boolean Defines whether the category is clickable in the Storefront.
templateName String Name of the category template.
parentCategoryKey String categoryKey of the parent category. null for the root category.
position Integer Sort weight of the category among its siblings. Siblings are ordered by this value in ascending order.
extraParentCategoryKeys Array categoryKey values of the additional parent categories.
localizedAttributes Array Localized attributes of the category, one entry per locale.
localizedAttributes.localeName String Locale name—for example, en_US.
localizedAttributes.name String Name of the category in the locale.
localizedAttributes.metaTitle String Meta title of the category in the locale.
localizedAttributes.metaDescription String Meta description of the category in the locale.
localizedAttributes.metaKeywords String Meta keywords of the category in the locale.
localizedAttributes.url String URL of the category in the locale. It is generated from the category name and the parent categories.
stores Array Names of the stores the category is assigned to.
imageSets Array Image sets of the category.
imageSets.localeName String Locale name of the image set. null for the default image set.
imageSets.name String Name of the image set.
imageSets.images Array Images of the image set.
imageSets.images.externalUrlSmall String URL of the small image.
imageSets.images.externalUrlLarge String URL of the large image.
imageSets.images.sortOrder Integer Order of the image within the image set.
isRoot Boolean Defines whether the category is the root category.

Retrieve a category

To retrieve a single category, send the request:

GET /categories/{{category_key}}

PATH PARAMETER DESCRIPTION
{{category_key}} Key of the category to retrieve. The key is matched case-insensitively. To get it, retrieve categories.

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.

Request sample: retrieve a category

GET https://glue-backend.mysprykershop.com/categories/computer

Response

Response sample: retrieve a category 
{
    "data": {
        "id": "computer",
        "type": "categories",
        "attributes": {
            "categoryKey": "computer",
            "isActive": true,
            "isInMenu": true,
            "isSearchable": true,
            "isClickable": true,
            "templateName": "CMS Block",
            "parentCategoryKey": "demoshop",
            "position": 100,
            "extraParentCategoryKeys": [],
            "localizedAttributes": [
                {
                    "localeName": "de_DE",
                    "name": "Computer",
                    "metaTitle": "Computer",
                    "metaDescription": "Computer",
                    "metaKeywords": "Computer",
                    "url": "/de/computer"
                },
                {
                    "localeName": "en_US",
                    "name": "Computer",
                    "metaTitle": "Computer",
                    "metaDescription": "Computer",
                    "metaKeywords": "Computer",
                    "url": "/en/computer"
                }
            ],
            "stores": [
                "DE",
                "AT"
            ],
            "imageSets": [],
            "isRoot": false
        },
        "links": {
            "self": "https://glue-backend.mysprykershop.com/categories/computer"
        }
    }
}
ATTRIBUTE TYPE DESCRIPTION
categoryKey String Unique key of the category. It is also the resource id.
uuid String Universally unique identifier of the category. Read-only. It is null on installations that do not have the optional uuid column, and on categories created before it was introduced until uuid:generate Category spy_category has been run for them. categoryKey, not uuid, is the resource id.
isActive Boolean Defines whether the category is active.
isInMenu Boolean Defines whether the category is shown in the Storefront navigation menu.
isSearchable Boolean Defines whether the category is searchable.
isClickable Boolean Defines whether the category is clickable in the Storefront.
templateName String Name of the category template.
parentCategoryKey String categoryKey of the parent category. null for the root category.
position Integer Sort weight of the category among its siblings. Siblings are ordered by this value in ascending order.
extraParentCategoryKeys Array categoryKey values of the additional parent categories.
localizedAttributes Array Localized attributes of the category, one entry per locale.
localizedAttributes.localeName String Locale name—for example, en_US.
localizedAttributes.name String Name of the category in the locale.
localizedAttributes.metaTitle String Meta title of the category in the locale.
localizedAttributes.metaDescription String Meta description of the category in the locale.
localizedAttributes.metaKeywords String Meta keywords of the category in the locale.
localizedAttributes.url String URL of the category in the locale. It is generated from the category name and the parent categories.
stores Array Names of the stores the category is assigned to.
imageSets Array Image sets of the category.
imageSets.localeName String Locale name of the image set. null for the default image set.
imageSets.name String Name of the image set.
imageSets.images Array Images of the image set.
imageSets.images.externalUrlSmall String URL of the small image.
imageSets.images.externalUrlLarge String URL of the large image.
imageSets.images.sortOrder Integer Order of the image within the image set.
isRoot Boolean Defines whether the category is the root category.

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 category with the specified key doesn’t exist, or the category specified in the parentCategoryKey parameter 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 categories resource. |

To view generic errors and status codes of the Backend API, see Backend API request and response reference.