Pages using the REST API

The REST API can be used to load pages. You can either fetch the page contents generated as JSON or HTML.

Request

The endpoint is available at https://core.helloretail.com/serve/pages/{key}. And fetches a page identified by key. The key for a page can be found on My Hello Retail.

You use it by sending an HTTP POST request with a JSON body. The content type must be application/json or text/plain ¹.

Example of the structure the JSON body must have when loading:

{
    "url": "https://example-shoe-shop-url.com/women/shoes",
    "id": 2,
    "format": "json",
    "firstLoad": true,
    "trackingUserId": "{tracking user id}",
    "params": {"filters":{"hierarchies": ["{hierarchy-1}", "{hierarchy-2}"]}},
    "products": {
        "start": 0,
        "count": 50,
        "fields": ["id", "title", "price"],
        "filters": [
            "brand:New Balance", "price:100,500"
        ],
        "sorting": [
            "title desc"
        ]
    }
}

More information about each part of the JSON body

Name	Type	Description
url	String (Required)	The url of the page. Used for analytics.
id	Integer	ID of a version of a page. Only needed if you want to fetch the Draft version of a page.
format	String	Specify the format in which the API will return the results. HTML and json are accepted values, the default value is HTML.
firstLoad	Boolean (Required)	Indicates if this is the first render of the page. This allows the template to only return some content on the first load. Views of the page will only be tracked if `firstLoad` is `true`. This also determines if available filters (facets) and sorting options should be returned
params	Object (Required)	Parameters that are passed as input to the page loading. Currently only the sub-object "filters" are used. Filters are used as a base filter when selecting products. See more below
trackingUserId	String	Hello Retail ID of the user visiting your site. This is used to apply personalization and for tracking purposes. You can get this ID server side by getting the value of the cookie named hello_retail_id.
products.start	Integer (Required)	Starting point when fetching products for the page.
products.count	Integer (Required)	Number of products to return from the starting point.
products.fields	String[]	Product fields to return when using the JSON response format. By default (without setting the parameter) all product fields will be returned. If you want to use product data from your database to render the products, and just need a way of knowing what products to include on the page, then you can pass "productNumber", and we will only return the productNumber for each product. You can then use the returned value to find the products in your database.
products.filters	String[]	List of filters to apply to the products. This will typically be filters enabled in a UI shown to the user to further limit the visible products, like for instance a range filter on price, or narrowing down products from a category based on brand
products.sorting	String[]	List sorting options to sort products by.

Base filters in params

The base filters in the params property are used to determine the gross list of products that the products.filters are applied to. This property allows complex AND/OR filters on any indexed field in your product catalog.

Examples:

By default, the filters at the root level of the filters parameter are ANDed together. The following will find products in the hierarchy Women›Shoes with the brand Nike

{
    "hierarchies": ["{hierarchy-1}", "{hierarchy-2}"],
    "brand": "{brand}"
}

The following examples are equivalent and will find products from the hierarchy Shoes or Shirts

{ 
    "hierarchies": {"$or": [["{hierarchy-1}"], ["{hierarchy-2}"]]} 
}

{ 
    "$or": [
        {"hierarchies": ["{hierarchy-1}"]},
        {"hierarchies": ["{hierarchy-2}"]},
    ] 
}

The following examples are equivalent and will find products that are in both the Female and the Shoes hierarchies

{ 
    "hierarchies": {
        "$and": [["{hierarchy-1}"], ["{hierarchy-2}"]]
    }
}

{
    "$and": [
        { "hierarchies": ["{hierarchy-1}"]},
        { "hierarchies": ["{hierarchy-2}"]}
    ] 
}

The filters can be combined and nested, like the following:

{
    "$or": [
        {
            "$and": [
                { "brand": "{brand}"},
                { "isOnSale": true }
            ]
        },
        { "brand": "NoName"}
    ]
}

Response

The response will be a JSON document. The content will depend on the requested format.

Example of a response with rendered HTML:

{
    "success": true,
    "firstLoad": true,
    "products": {
        "start": 0,
        "count": 50,
        "total": 500,
        "html": "<div>Products rendered using the design selected for the page</div>",
        "javascript": "/* javascript from the design selected for the page */",
        "style": "/* css from the design selected for the page */"
    }
}

Example of a response with JSON formatted products

{
    "success": true,
    "firstLoad": true,
    "products": {
        "start": 0,
        "count": 50,
        "total": 500,
        "result": [
            {
                "title": "abc",
                "url": "{product url}",
                "imgUrl": "{image url}",
                "currency": "DKK",
                "priceLowered": true,
                "description": "sample description",
                "keywords": "ab, gh, dd",
                "inStock": true,
                "productNumber": "{product number}",
                "variantProductNumbers": [],
                "price": 233.44,
                "previousPrice": 500.23,
                "score": 7.0
            },
            ...
        ]
    }
}

The reason for supporting text/plain is to allow requests to this endpoint, made from the browser, to be categorized as simple thereby avoiding CORS preflight requests. You can read more here https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests ↩