Integration Best Practices
The following section discusses the best practices that will help ensure the integration is implemented in the most efficient way.
Response Sizes
Enable the compression of responses by including the required header value in every request that gets sent. This reduces bandwidth and throughput time considerably.
Use the Display Fields configuration page in the Merchandising Studio to control the amount of information that gets included in each response.
Avoid using a fh_view_size value > 50, as doing so will result in large responses that might take too long to transfer.
DNS Resolving and Caching
Do not use HTTP Keep-Alive, as this might result in unexpected time-outs and connections closings.
Resolve the DNS name each time the front-end sends a query request. If for some reason this is absolutely not working as described and it is not possible due to limitations of the consumed front-end infrastructure or the specifics of the application, we suggest the following work-around heuristics:
Resolve the DNS record into the full list of IP addresses (e.g. using nslookup, dig or similar tools).
Implement the Round-robin DNS by sending every new request to the next IP in the list (iterating over the list infinitely).
Refresh the list every X regularly (every 5 to 10 minutes) OR in case of errors.
Make sure that the DNS caching respects advertised TTL.
If IP address filtering/whitelisting policies apply, we advise to regularly resolve the query endpoint, e.g. every 4-6 hours, and the returned IP addresses should be added to your whitelist.
The following request is for a query to be sent to the endpoint of fas:live1 in the EU1 region and the DNS name was returned as 123.45.67.89:
Make sure to set the Host value in the header section of the http request when sending queries to Fredhopper using an IP address. If this is omitted, the request will result in a 404 error response code.
Fail-Safety
Set a timer for each query. The time out setting can be different for different types of queries.
Implement a single retry for any responses from Fredhopper that contain a HTTP code 5xx.
Do not query with textual terms longer than 40 characters, the front-end should ideally cap these long $s= terms.
Implementation Optimisations
If possible, keep a cache of query responses to use for repeated requests within a given time period. Do not refresh all cached query responses at once, as this may cause spikes in requests to the API, leading to service instance resource saturation.
Do not stream process the responses as they are sent back from Fredhopper. Instead, store each response immediately in a container and then process the container. This will prevent slow streaming on the front-end potentially blocking the query servers and result in a dead-lock situation that is difficult to identify on both sides.
Log the round trip time and the actual query (fh_location=.... etc) for each query sent. Example format: yyyymmdd hh:mm:ss:msmsms TZONE <roundtrip time in milliseconds> <IP of response> <HTTP STATUS> <Bytes> <query>. Be sure to rotate these files daily.
Extend the Fredhopper Queries with fh_session=<keyword> parameters for traceability. With the proper usage of these keywords, the Fredhopper Teams can identify the types of queries that are being sent and spot potential issues. Suggested keywords values include:
fh_session=frontend_cache_refresh, appended to any front-end cache refresh queries.
fh_session=frontend_monitoring, used for front-end monitoring queries.
fh_session=frontend_userquery, used for front-end user queries.
Please allow fh_session parameter value to be overwritten by a cookie that can be set on browser with cookie settings. This can be very useful later on while investigating integration sanity on query usage investigations, ensuring the correct amount of queries sent to Fredhopper per shopper action on site.
Monitoring
Ensure DNS lookups are fast. Unavailable local DNS server may impose increased RTT.
Setup external monitoring, e.g. Statuscake, so connectivity and ISP-related issues can be easily traced.
Ensure a fast and short route from the front-end web application to the Fredhopper endpoints. Tracing the route could be of help.
Monitor your bandwidth and measure the maximum throughput.
Last updated