Data Integration and Orchestration

Optimizing server requests through data integration and orchestration is essential for frontend performance. This guide introduces the orchestration feature, highlighting its role in integrating extensions and streamlining frontend code.

Enhancing Frontend Performance through Data Orchestration

Data orchestration allows for consolidating multiple server requests into a single endpoint, which significantly eases the burden on the frontend. This is particularly beneficial in scenarios involving numerous simultaneous server requests.

Advantages:

• Minimized Network Traffic: Fewer server calls lead to reduced latency and enhanced responsiveness.
• Simplified Frontend Architecture: By grouping related server requests, the frontend logic becomes less complex.
• Uniform Data Collection: Ensures that data fetched from different sources is consistent and provided in a standard format.

Implementation:

The getApiClient Method

If you want to retrieve a loaded integration within the context of another, you can use the getApiClient method. This method serves as a bridge between various integrations, ensuring seamless data flow and interaction.

Usage:

const sapcc = context.getApiClient("sapcc");

The getApiClient method takes a single argument, which is the key of the api client you wish to retrieve. This is the key you would define in the middleware.config.js file for the integration you wish to retrieve. The key is essentially an identifier for the integration.

Here's a basic example of what this might look like:

export const integrations = {
  sapcc: {
    location: "@vsf-enterprise/sapcc-api/server",
    configuration: {
      // ...
    },
    extensions: (extensions) => [
      ...extensions,
      {
        name: "sapcc-contentful-extension",
        extendApiMethods: {
          getPDP: async (context, params: { id: string }) => {
            const sapccApi = context.api; // You can access integration methods directly
            const contentful = context.getApiClient("contentful"); // You can access other integrations using getApiClient

            const [product, content] = Promise.all(
              sapccApi.getProduct({ id: params.id }),
              contentful.api.getEntries({
                content_type: "product",
                "fields.sku": params.id,
              })
            );

            return {
              product,
              content,
            };
          },
        },
      },
    ],
  },
  contentful: {
    location: "@vsf-enterprise/contentful-api/server",
    configuration: {
      // ...
    },
  },
};

1. Extend the integration with new endpoint: Create a new endpoint that will act as the main entry point for the grouped requests.
2. Group Server Requests: Within this endpoint, utilize the getApiClient method to retrieve and interact with the required integrations.
3. Aggregate Data: Once data from all required integrations is retrieved, aggregate and format it as needed.
4. Return Unified Response: Send a consolidated response back to the frontend.

Using orchestration methods in the frontend

To call the orchestration endpoint, you can follow the Using extension methods in the frontend guide.

Real-World Examples

The examples provided demonstrate practical uses of data orchestration:

Example 1: Fetching Custom Product Properties from Legacy Systems

This use case involves calling the commerce backend to fetch specific product data. Additionally, a separate call is made to a legacy custom system of the customer, to retrieve a custom product property (e.g., stock of the product). This data is used, for example, to display stock information on the product page.

Example implementation might look like this:

export const integrations = {
  sapcc: {
    // ...
    extensions: (extensions) => [
      ...extensions,
      {
        name: "orchestration-extension",
        extendApiMethods: {
          enrichedSearch: async (context, params: { productId: string }) => {
            const sapccApi = context.api;
            const legacyCustomSystem = context.getApiClient("legacyCustomSystem");

            const [prouctStock, product] = await Promise.all([
              legacyCustomSystem.api.getProductStock({
                productId: params.productId,
              }),
              sapccApi.getProduct({
                { id: params.productId },
              }),
            ]);

            return {
              ...product,
              stock: productStock,
            };
          },
        },
      },
    ],
  },
  legacyCustomSystem: {
    // ...
  },
};

TypeScript Support

getApiClient helper returns the ApiClient interface, which is a generic type. It takes three type arguments:

• Api - the type of the API object returned by the integration,
• Config - the type of the configuration object passed to the integration,
• Client - the type of the HTTP client object returned by the integration.

Usually, an integration exports those types. For example, the sapcc integration exports the following types:

import {
  Endpoints,
  MiddlewareConfig,
  AxiosInstance,
} from "@vsf-enterprise/sapcc-api";