Preparing SPARQUE Desk for Populating a Product Detail Page
The Wrapper endpoint /product returns product details from SPARQUE Desk and is intended for populating a product detail page (pdp). The Wrapper endpoint /product-attributes returns product attributes from SPARQUE Desk and is intended for supplementing the content of a product detail page.
In SPARQUE Desk, multiple endpoints are required for this:
- pdp
- attributes
- variation_attributes
- variants
Note:
The SPARQUE product object includes attributes such as name, brand and description. Additional details, such as color, are not stored directly in the product object. Instead, products are linked to related objects such ashttps://www.sparque.ai/propertyname, andhttps://www.sparque.ai/propertyvalue. These related objects are also valuable for populating product detail pages.
Result Descriptions
The configuration of result descriptions for these endpoints is crucial, as it determines the format of SPARQUE Desk responses required by the Wrapper.
How it Works
When the /product Wrapper endpoint is called, the Wrapper triggers a SPARQUE Desk request to /pdp, which returns the main product object. The result description must include references to both productMaster and productVariant at the corresponding result level of the endpoint.
Next, the Wrapper makes a second SPARQUE Desk request to /variants (stacked on top of /pdp) to retrieve all possible variations of the requested product. If the provided SKU has a master SKU, the Wrapper also requests /variation_attributes to obtain relevant attribute data.
This sequence ensures that the Wrapper gathers all the necessary information to fully populate a product detail page.
Endpoint pdp
This endpoint is called by the /product Wrapper endpoint to return a product object. It requires an sku parameter (string) to identify the product. The endpoint is designed for rendering a product detail page in the storefront. It uses a simple strategy where it applies a filter by SKU and returns the matching product.
pdp/p/sku/{STRING}/p/channel/{STRING} -> OBJExample strategy:
If no further configuration is made in SPARQUE Desk, the /pdp endpoint will output the product details as defined in the result description. To additionally display variant or master information, the result description must be extended accordingly.
Result description example:
{
"class": "https://www.sparque.ai/product",
"level": 5,
"mode": "full",
"attributes": [
{
"name": "description",
"type": "STRING",
"aggr": "most_frequent"
},
{
"name": "type",
"type": "STRING",
"aggr": "most_frequent"
},
{
"name": "primaryImageId",
"type": "STRING",
"aggr": "most_frequent",
"splitLanguages": true
},
{
"name": "name",
"type": "STRING",
"aggr": "most_frequent"
},
{
"name": "short-description",
"type": "STRING",
"aggr": "most_frequent"
},
{
"name": "sku",
"type": "STRING",
"aggr": "most_frequent",
"splitLanguages": true
},
{
"name": "supplier-sku",
"type": "STRING",
"aggr": "most_frequent",
"splitLanguages": true
},
{
"name": "position",
"type": "INTEGER",
"aggr": "most_frequent"
},
{
"name": "price",
"type": "DOUBLE",
"aggr": "most_frequent"
}
],
"constants": [],
"includes": [
{
"class": [
"https://www.sparque.ai/product"
],
"cardinality": "*",
"level": 6,
"prefix": "productVariants",
"dense": false,
"predicate": "hasMasteredProduct",
"reverse": false
},
{
"class": [
"https://www.sparque.ai/product"
],
"cardinality": "*",
"level": 6,
"prefix": "productMaster",
"dense": false,
"predicate": "hasMasteredProduct",
"reverse": true
},
{
"class": [
"https://www.sparque.ai/image"
],
"cardinality": "*",
"level": 6,
"prefix": "images",
"dense": false,
"predicate": "hasImage",
"reverse": false
}
]
}Endpoint attributes
This endpoint retrieves all property names and values (e.g., color | red) for a specific product. The /product-attributes Wrapper endpoint uses it to supply attributes that are not stored directly within the product object.
An sku parameter is required to identify and filter the relevant product. The configured strategy traverses related entities to gather all associated property values and return them to the Wrapper.
The returned property value objects must include at least the name and value attributes. This endpoint is particularly useful for controlling which property values are visible to the application, as the strategy can easily be adjusted to determine which values are exposed.
attributes/p/sku/{STRING} -> OBJExample strategy:
Example result description, using only the propertyvalue object:
{
"class": "https://www.sparque.ai/propertyvalue",
"level": 1,
"mode": "full",
"attributes": [
{
"name": "identifier",
"type": "STRING",
"aggr": "most_frequent",
"splitLanguages": true
},
{
"name": "name",
"type": "STRING",
"aggr": "most_frequent"
},
{
"name": "value",
"type": "STRING",
"aggr": "most_frequent"
}
],
"constants": [],
"includes": []
Example result description, including the propertyname object for localized names and for a visible flag:
{
"class": "http://schema.org/PropertyValue",
"level": 1,
"mode": "full",
"attributes": [
{
"name": "id",
"type": "STRING",
"aggr": "most_frequent"
},
{
"name": "identifier",
"type": "STRING",
"aggr": "most_frequent"
},
{
"name": "value",
"type": "STRING",
"aggr": "most_frequent"
}
],
"constants": [],
"includes": [
{
"class": [
"http://schema.org/PropertyName"
],
"cardinality": "*",
"level": 8,
"prefix": "propertyName",
"dense": false,
"predicate": "propertyOf",
"reverse": false
}
]
},
{
"class": "http://schema.org/PropertyName",
"level": 8,
"mode": "full",
"attributes": [
{
"name": "id",
"type": "STRING",
"aggr": "most_frequent",
"splitLanguages": true
},
{
"name": "identifier",
"type": "STRING",
"aggr": "most_frequent"
},
{
"name": "name",
"type": "STRING",
"aggr": "auto_set",
"splitLanguages": true
},
{
"name": "visible",
"type": "INTEGER",
"aggr": "auto_set"
}
],
"constants": [],
"includes": []
}Endpoint variation_attributes
This endpoint is called by the /product Wrapper endpoint and must return an array of objects in the format [master, variant, propertyValue]. The Wrapper uses this data to retrieve the variation attributes of master products, enabling users to select different variants - such as various colors or sizes - on the product detail page.
variation_attributes/p/sku/{TUPLE_LIST} -> OBJ,OBJ,OBJExample strategy:
Endpoint variants
This endpoint retrieves related variant products, allowing users to view and select alternative options for the same product on the product detail page.
OBJ -> variants -> OBJExample strategy: