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 Methodsri:link

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 */
});

Data Federationri:link

Sometimes you need to combine data from multiple integrations (e.g., your eCommerce backend + CMS) into a single response. This is called Data Federation.

Use context.getApiClient() to access other integrations within your custom methods:

import type { SapccIntegrationContext } from '@vsf-enterprise/sapcc-api';
import type { Endpoints as ContentfulEndpoints } from '@vsf-enterprise/contentful-api';

export async function getProductWithContent(
  context: SapccIntegrationContext,
  args: { productId: string }
) {
  // Access the CMS integration
  const cms = await context.getApiClient<ContentfulEndpoints>("contentful");
  
  // Fetch from both sources in parallel
  const [product, content] = await Promise.all([
    context.api.getProduct({ id: args.productId }),
    cms.api.getEntries({
      content_type: "product",
      "fields.sku": args.productId,
    }),
  ]);

  return { product, content };
}

Key Points:

• The integration key ("contentful") must match your middleware.config.ts configuration
• Pass the integration's Endpoints type as a generic for type safety
• Use Promise.all() to fetch from multiple sources concurrently

How it works under the hoodri:link

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.