Creating New API Methods

When building your Storefront, you may need additional functionality beyond Unified Data Methods. To achieve this, you can add custom methods.

The following guide will show you how to create the Unified Data Layer API methods.

Adding New API Methods

To implement a new API method, you have to:

1. Define input and output types of your method in apps/storefront-middleware/api/custom-methods/types.ts, for example:

export interface CustomMethodPageArgs {
  // your arguments
}

export interface CustomMethodResponse {
  // interface for the response
}

2. Modify a custom.ts file in apps/storefront-middleware/api/custom-methods/custom.ts which contains the method implementation.

import { type IntegrationContext } from "../../types";
import type { CustomMethodArgs, CustomMethodResponse } from "./types";

/**
 * @description
 * Boilerplate custom method to be replaced
 *
 * More information can be found at {@link https://docs.alokai.com/unified-data-layer/integration-and-setup/creating-new-api-methods}
 */
export async function exampleCustomMethod(
  context: IntegrationContext,
  args: CustomMethodArgs
): Promise<CustomMethodResponse> {
  // your implementation
  return {};
}

3. Last step is to export the method in the apps/storefront-middleware/api/custom-methods/index.ts file.

export { exampleCustomMethod } from "./custom";

Now, thanks to the SDK synchronization, the exampleCustomMethod method will be available and typed under custom namespace when you use the SDK in your Storefront.

// Storefront project
const { data } = sdk.customExtension.exampleCustomMethod({
  /* args */
});

Using Unified Methods in Custom Methods

When creating a custom method, you can use the Unified Data Layer API methods to fetch data from your backend. This is useful when you want to extend the existing API methods with additional data or when you want to use the existing methods to fetch data from your backend.

For example, you can use the getProductDetails method to fetch product details from your backend and then extend the response with additional data.

import { methods } from "@vsf-enterprise/unified-api-sapcc";
import type { SapccIntegrationContext } from "@vsf-enterprise/sapcc-api";
import type {
  GetProductDetailsExtendedArgs,
  GetProductDetailsExtendedResponse,
} from "./types";

export async function getProductDetailsExtended(
  context: SapccIntegrationContext,
  args: GetProductDetailsExtendedArgs
): GetProductDetailsExtendedResponse {
  // fetch product details from your backend
  const response = await context
    .getApiClient("commerce")
    .getProductDetails(args);

  // use the response and add additional data
  return {
    ...response,
    data: "Additional data",
  };
}

Data Federation

Data Federation allows you to consolidate multiple server requests into a single endpoint. For example, if you want to fetch data from your CMS, query your eCommerce backend, and return a single response containing all the information.

When creating/overriding an API method, you can query multiple services using the getApiClient method. This method will search your integrations defined in your Middleware Configuration, find one matching a specific key, and return that integration's API client.

For example, we can use Data Orchestration to add additional product information from our CMS when creating a custom getCmsPage method.

import type { SapccIntegrationContext } from "@vsf-enterprise/sapcc-api";
import { methods } from "@vsf-enterprise/unified-api-sapcc";
import type { GetCmsPageArgs, GetCmsPageResponse } from "./types";

export async function getCmsPage(
  context: SapccIntegrationContext,
  args: GetCmsPageArgs
): GetCmsPageResponse {
  const { id } = args;
  // fetch data from your CMS integration
  const { productIds, page } = await context.getApiClient("cms").getPage(id);

  // fetch products data from your eCommerce backend
  const products = await methods.getProducts(context, {
    ids: productIds,
  });

  // if you don't want to use the Unified Methods,
  // you can use the commerce API Client directly from `context.api`

  return {
    ...page,
    products,
  };
}

const config = {
  integrations: {
    //
    cms: {
      location: "@vsf-enterprise/[cms-integration]-api/server",
      //...
    },
    // ...
  },
};

How it works under the hood

Under the hood, methods you add in apps/storefront-middleware/api/custom-methods/index.ts are registered in a middleware extension. Extensions give you more capabilities than just adding new methods. Find more about in Extending the Middleware guide.