Migration: Wrapper Version 1.9.0

• Adjusted category facet handling - Full category tree returned with intelligent filtering based on selected categories.
• Adjusted facet filtering - Removed automatic filtering of fixed facets for consistent handling.
• Improved sorting behavior - Sortings are now applied at the end of stacked calls for better performance.
• Modified data types of custom attributes - Custom attributes now preserve their original types instead of being cast to strings.

All endpoints in API v4 follow the same structure as in API v3, but with updated functionality as described below.

• Deprecation status: API v3 is still functional but will no longer receive updates or new features.
• Removal timeline: API v3 will be retired in the future. The removal date will be announced well in advance to allow sufficient time for migration.
• Impact: Once API v3 is retired, all requests to v3 endpoints will result in errors.
• Action required: We strongly recommend migrating to API v4 as soon as possible to ensure uninterrupted service.

• /api/v4/facet-options
• /api/v4/products
• /api/v4/search

1. Returned facet options for the fixed facet category: Multiple changes have been made to the behavior of the API in relation to the fixed facet category:
   • If no category is passed to the API via the SelectedFacets parameter, the full category tree relevant to the product search result is returned (with root categories represented by the facet options and their child facets populated accordingly).
   • If a category is passed to the API via the SelectedFacets parameter, this will also return the full category tree, but will apply additional filters. Any node in the returned tree needs to fulfill at least one of the following criteria, else it will not be included in the response:
     • The node matches the selected category filter.
     • The node is a sibling of the node matching the selected category filter.
     • The node is an ancestor (parent, grandparent, etc.) of the node matching the selected category filter.
     • The node is a descendant (child, grandchild, etc.) of the node matching the selected category filter.
   • Category facet groups are now returned even if they have only a single option that matches the full product result list. Other fixed facets are not affected by this change.
2. Added error message when providing multiple categories for the SelectedFacets parameter: If multiple categories are provided as SelectedFacets, only one of them will be taken into account for the logic described above. The remaining categories will still be applied to the underlying search logic. An error message highlighting this inconsistency, should multiple categories be supplied, has been added to the response.
3. Removed localizedNames and localizedValues fields: Categories provided as part of the childFacets field previously included a list of localized names and descriptions. These values will no longer be part of the response to keep the behavior of root and child category facets consistent.

The changes to the SPARQUE API Wrapper described here rely on the SPARQUE category_facets endpoint returning the full category tree. The default strategy limits the depth of the tree to five levels. If your tree has more than five levels, adjust the strategy accordingly.

• /api/v4/facet-options
• /api/v4/products
• /api/v4/search

1. Removed automatic filtering of fixed facets The SPARQUE API Wrapper previously filtered out fixed facets from the result set when the following conditions were met:

   • The facet has only a single option
   • The score of that option is equal to the total number of products

   This filtering logic has been removed from all Wrapper endpoints that return facets, so fixed and dynamic facets are handled equally.

2. Selected facets now available as a parameter To support custom filtering logic in strategies, the SelectedFacets parameter of the /facet-options endpoint is now passed to the SPARQUE /facet_options and /facet_options_lc endpoints as the parameter clicked_facets in tuple format.

To maintain the previous filtering behavior or implement custom filtering logic:

• Update the SPARQUE endpoints for /facet_options or /facet_options_lc to accept the clicked_facets parameter with a {TUPLE_LIST} value
• Update the SPARQUE strategies for /facet_options or /facet_options_lc to apply the desired filter logic

• /api/v2/products and newer
• /api/v2/recommendations and newer
• /api/v2/search and newer
• /api/v2/suggestions and newer

Sortings moved to the end of stacked calls

Previously, the Wrapper applied sortings (e.g., /q/nameup) too early in stacked calls, which could lead to unwanted results like completely resetting the sorting (depending on the implementation of the stacked endpoints that come after the sorting). This could also have a negative impact on performance, as the sorting was applied to the intermediate result set instead of the final, possibly smaller result set. To address this, the sorting is now applied at the end of stacked calls.

• Previous URL for a search:
  • https://rest.sparque.ai/1/intershop-project-base-v2-team2/api/PWA/c/locale/de-DE/c/channel/ish/c/keyword/micro/e/search/q/nameup/e/oneVariant/results
• New URL for a search:
  • https://rest.sparque.ai/1/intershop-project-base-v2-team2/api/PWA/c/locale/de-DE/c/channel/ish/c/keyword/micro/e/search/e/oneVariant/q/nameup/results

• Categories
• Products
• Product images
• Attachments
• SparqueFacetOptions
• FixedFacetOption

• /api/v4/categoryTree
• /api/v4/pdp
• /api/v4/recommendations
• /api/v4/search
• /api/v4/suggest

"customField1": "customValue_11",
"customField2": 24,
"customBoolean": false,
"customObject": {
	"someValue": 4321
},
"customComplex": {
	"first": {
		"second": "terce"
	},
	"anInt": 4321
}

Note: Locale filtering: When the attribute is a map with locales (e.g.: "en-US") as keys, only the value of the requested locale is returned by the Wrapper. This behavior has not changed compared to the previous versions.

• /api/v2/facet-options and newer
• /api/v2/products and newer
• /api/v2/search and newer

The Wrapper API response for fixed and dynamic facets has been enhanced to include additional attributes for individual facet options if such attributes are supplied by SPARQUE.AI.

Example for a fixed facet with additional attributes:

{
    "id": "category",
    "title": "Kategorie",
    "rank": 1,
    "options": [
        {
            "id": "Computers",
            "score": 951.0,
            "value": "Computer",
            "attributes": [
                {
                    "name": "description",
                    "value": {
                        "de-DE": "Der Produkt- und Servicekatalog für Computer.",
                        "en-US": "The Computers products and services catalog.",
                        "fr-FR": "Le catalogue des services et produits informatiques."
                    }
                },
                {
                    "name": "online",
                    "value": 1
                },
                {
                    "name": "root",
                    "value": 1
                }
            ]
        },
        [...]
    ],
    "attributes": [
        [...]
    ]
}

Example for a dynamic facet with additional attributes:

{
    "id": "https://www.sparque.ai/ish/category/network-cables",
    "identifier": "network-cables",
    "score": 25.0,
    "value": "Network Cables",
    "localizedNames": {[...]},
    "localizedValues": {[...]},
    "childFacets": [],
    "attributes": [
        {
            "name": "image",
            "value": "M/28918-6725.jpg"
        },
        {
            "name": "online",
            "value": 1
        },
        {
            "name": "root",
            "value": 0
        }
    ]
}

As part of this update, the structure of the SPARQUE endpoints used by the Wrapper to retrieve fixed facet options has been updated.

Previous format:

[...]/options/{fixedFacetName}

Adjusted format:

[...]/e/{fixedFacetName}/results

For dynamic facets, no modifications to SPARQUE are required. If the tuples returned by the facet_options or facet_options_lc endpoints include additional attributes, these attributes will automatically be available in the Wrapper response.

For fixed facets, however, changes to SPARQUE are necessary to support additional attributes. By default, the existing facet strategies and endpoints for fixed facets typically return only a string value, not an object. To enable the display of additional attributes for fixed facets, the SPARQUE endpoints must be updated to return objects containing the relevant fields. Additionally, the corresponding strategy needs to be adjusted accordingly. For details, refer to Defining Fixed Facets in a List or Search Result Page.

The updated mapping in the Wrapper is compatible with both the old and new formats, ensuring backwards compatibility.