Modify requests and responses

This is for:

Developer

For advanced use cases, such as modifying request bodies with custom parameters or logging data to third parties, you may want to modify requests before Atomic sends them to the Coveo APIs. You may also want to modify responses before Atomic components use them. This article explains how you can do so using Headless engine configuration methods.

Modify requests

To modify requests sent to the Coveo Search API or the usage analytics Write API, use the preprocessRequest method of the search engine configuration when initializing your interface.

Important

The preprocessRequest method is a powerful tool, and it can be leveraged to do things that should be done in a different manner. For example, you can use it to set aq, but you should use the Headless AdvancedSearchQuery action instead. You can use them in Atomic as well.

If you have to use preprocessRequest, you should code defensively. For example, you can implement try…​catch to prevent errors.

 
<script>
  (async () => {
    await customElements.whenDefined('atomic-search-interface');
    const searchInterface = document.querySelector(
      'atomic-search-interface'
    );

    // Initialization
    await searchInterface.initialize({
      accessToken: 'xx564559b1-0045-48e1-953c-3addd1ee4457',
      organizationId: 'searchuisamples',
      organizationEndpoints: await searchInterface.getOrganizationEndpoints('searchuisamples'),
      preprocessRequest: (request, clientOrigin, metadata) => { 1
        if (metadata?.method === 'search' && clientOrigin === 'searchApiFetch') {
          const body = JSON.parse(request.body);
          // E.g., modify facet requests
          // body.facets = [...];
          request.body = JSON.stringify(body);
        }

        if (clientOrigin === 'analyticsFetch') {
          // E.g., send data to a third party
        }

        return request;
      },
      // ...
   });

    // Trigger a first search
    searchInterface.executeFirstSearch();
  })();
</script>
1 Initialize the function with its parameters:

  • request: The HTTP request sent to Coveo. See preprocess-request.ts.

  • clientOrigin: The origin of the request. See preprocess-request.ts.

  • metadata: Optional metadata consisting of two properties:

    • method: The method called on the client.

    • origin: The origin of the client that helps to distinguish between features while using the same method.

    See search-metadata.ts.

Modify responses

You can also leverage the search configuration options to modify Search API responses before Headless controllers use them. Use the preprocessSearchResponseMiddleware, preprocessFacetSearchMiddleware or preprocessQuerySuggestResponseMiddleware method, depending on the target endpoint.

<script>
  (async () => {
    await customElements.whenDefined('atomic-search-interface');
    const searchInterface = document.querySelector(
      'atomic-search-interface'
    );

    // Initialization
    await searchInterface.initialize({
      accessToken: 'xx564559b1-0045-48e1-953c-3addd1ee4457',
      organizationId: 'searchuisamples',
      organizationEndpoints: await searchInterface.getOrganizationEndpoints('searchuisamples'),
      // ...
      search: {
        preprocessSearchResponseMiddleware: (response) => {
          response.body.results.forEach((result) => {
            // E.g., modify the result object
            return result;
          });
          return response;
        },
        preprocessFacetSearchResponseMiddleware: (response) => response,
        preprocessQuerySuggestResponseMiddleware: (response) => response,
     },
   });
    // Trigger a first search
    searchInterface.executeFirstSearch();
  })();
</script>