Retrieving Navigation Trees

Edit on GitHub

Spryker offers the navigation feature, which enables shoppers to quickly navigate the shop and easily locate the necessary products and other content. For this purpose, backoffice users can create any number of navigations. Navigations come in a tree structure and can incorporate links to CMS pages, categories, as well as any other internal and external links.

The Navigation API provides the possibility to retrieve any navigation tree configured in Spryker.

The resources exposed by the API provide access to complete navigation trees only. Access to specific navigation elements is not supported.

In your development, these resources can help you to retrieve all kinds of navigations available in Spryker and build navigation menus to guide customers through.

For more details on managing navigation trees, see Navigation.

Installation

For detailed information on the modules that provide the API functionality and related installation instructions, see Navigation.

Usage

To retrieve a navigation tree with detailed information on each node, send a GET request to the following endpoint: /navigations/{{navigation_id}} Request sample: GET http://mysprykershop.com/navigations/SOCIAL_LINKS where SOCIAL_LINKS is the ID of the navigation tree you want to retrieve.

Navigation IDs are case sensitive.

If the request was successful, the resource responds with a **RestNavigationResponse**.

Response Fields

Field* Type Description
name String Specifies the tree name.
isActive Boolean Specifies whether the tree is active.
If the value of the field is true, the tree should be displayed to the customer. Otherwise, the tree should be hidden.
locale
nodes Array Specifies an array of node elements that comprise the navigation tree.

In addition to that, each node element exposes the following fields:

Field Type Description
title String Specifies the title that should be used to display the node anywhere on the frontend.
url String Specifies the URL link the node points to.
If the node_type parameter is set to cms_page, category or link, the URL is relative to the application domain. For example, /en/product-sets.
  • If the node_type parameter is set to external_url, the URL contains an absolute URI. For example, http://example.com/mypage.html.
  • If the node_type parameter is set to external_url, the URL contains an absolute URI. For example, http://example.com/mypage.html.
  • If the node_type parameter is set to label, the URL is always empty, because labels are intended to be text-only elements.
isActive Boolean Specifies whether the node is active.
If the value of the field is true, the node should be displayed to the customer. Otherwise, the node should be hidden.
nodeType String Specifies the node type. Should be one of the following values:
  • label - specifies a simple label (text-only element);
  • cms_page - specifies a link to a CMS page;
  • category - specifies a link to a category page;
  • link - specifies a link to any page within the shop;
  • external_url - specifies a link to an external web site.
cssClass String Specifies the CSS class to be used to render the node.
validFrom String Specifies a date that the node is valid from.
validTo String Specifies a date that the node is valid to.
children Array Specifies an array of node elements that are nested within the current element.

*The fields mentioned are all attributes in the response. Type and ID are not mentioned.

Sample Response

{
    "data": {
        "type": "navigations",
        "id": "SOCIAL_LINKS",
        "attributes": {
            "name": "Social links",
            "isActive": true,
            "locale": null,
            "nodes": [
                {
                    "isActive": true,
                    "nodeType": "external_url",
                    "title": "Twitter",
                    "url": "https://twitter.com/sprysys?lang=de",
                    "cssClass": "twitter",
                    "validFrom": null,
                    "validTo": null,
                    "children": []
                },
                {
                    "isActive": true,
                    "nodeType": "external_url",
                    "title": "Xing",
                    "url": "https://www.xing.com/companies/sprykersystemsgmbh",
                    "cssClass": "xing",
                    "validFrom": null,
                    "validTo": null,
                    "children": []
                },
                {
                    "isActive": true,
                    "nodeType": "external_url",
                    "title": "LinkedIn",
                    "url": "https://www.linkedin.com/company/spryker-systems-gmbh",
                    "cssClass": "linkedin",
                    "validFrom": null,
                    "validTo": null,
                    "children": []
                },
                {
                    "isActive": true,
                    "nodeType": "external_url",
                    "title": "YouTube",
                    "url": "https://www.youtube.com/channel/UC6lVOEbqXxUh0W5FMTvlPDQ",
                    "cssClass": "youtube",
                    "validFrom": null,
                    "validTo": null,
                    "children": []
                }
            ]
        },
        "links": {
            "self": "http://mysprykershop.com/navigations/SOCIAL_LINKS"
        }
    }
}

You can also use the Accept-Language header to specify the locale.
Sample header:
[{"key":"Accept-Language","value":"de, en;q=0.9"}]
where de and en are the locales; q=0.9 is the user’s preference for a specific locale. For details, see 14.4 Accept-Language.

Possible Errors

Code Reason
400 Navigation ID is not specified.
404 Navigation not found.