Creating new API Methods

When working with the Storefront, you may need additional functionality beyond the Unified Methods provided by Alokai. In this guide, you will learn how to add your own, custom methods working with the Unified Data Layer and accessible in your Storefront via the Alokai SDK.

Before following this guide, make sure you are using @vsf-enterprise/unfied-api-<integration> version 1.0.0 or higher and migrate if needed.

Alokai Storefront project have a pre-baked custom extension in the storefront-middleware app. It automatically registers custom methods in your Server Middleware under the /custom namespace. The extension file can be found in apps/storefront-middleware/integrations/sapcc/extensions/custom.ts.

If the extension is present in your project, you follow the version of the guide which only mentions creating a custom method. If it's not - follow the version which describes both creating a custom method and registering a custom extension from scratch.

Creating a custom API Method

To create a custom API Method, you will work with files in the apps/storefront-middleware directory. Code examples in this guide feature our SAP Commerce Cloud integration. However, the process looks the same for all Alokai integrations.

Define types for the new method

Navigate to the types.ts file and create two inferfaces: one for the arguments and one for the response of your new method:

/apps/storefront-middleware/api/custom-methods/types.ts

export interface CustomMethodPageArgs {
  someArg: string
}

export interface CustomMethodResponse {
  someKey: string;
}

Implement the method

In the middleware application, navigate to the custom.ts file and implement the new method:

apps/storefront-middleware/api/custom-methods/custom.ts

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

export async function exampleCustomMethod(
  context: IntegrationContext,
  args: CustomMethodArgs
): Promise<CustomMethodResponse> {
  // your method implementation
  return {};
}

Export the method

Navigate to the index.ts file and export the new method from the custom.ts file:.

apps/storefront-middleware/api/custom-methods/index.ts

export { exampleCustomMethod } from "./custom";

Using the custom API method in the frontend

With the custom API method in place, you can now call it in your frontend code using Alokai SDK:

apps/storefront-unified-nextjs/components/some-component.tsx

import { getSdk } from '@/sdk';

export default async function SomeComponent() {
  const sdk = getSdk();
  
  const { someKey } = await sdk.customExtension.exampleCustomMethod({ someArg: 'whatever' });

  return <p>Some HTML</p>;
}

Extending the existing Unified Methods

Below is an example of accessing Unified Methods of the integration registered under the commerce key in middleware.config.ts:

apps/storefront-middleware/api/custom-methods/getProductDetailsExtended.ts

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

export async function getProductDetailsExtended(
  context: Context,
  args: GetProductDetailsExtendedArgs
): GetProductDetailsExtendedResponse {
  // access the commerce client
  const commerceClient = await context.getApiClient("commerce");
  // fetch product details from your backend
  const response = await commerceClient.api.unified.getProductDetails(args);

  // inject additional data into response
  return {
    ...response,
    data: "additional data",
  };
}

Composing unified data from multiple services

Below is an example of accessing Unified Methods of the integrations registered under commerce and cms keys in middleware.config.ts, fetching data from both platforms and returning a single response containing all the information.

apps/storefront-middleware/api/custom-methods/getCmsPage.ts

import type { ContentfulIntegrationContext as Context } from "@vsf-enterprise/contentful-api";
import type { GetCmsPageArgs, GetCmsPageResponse } from "./types";

export async function getCmsPage(
  context: Context,
  args: GetCmsPageArgs
): GetCmsPageResponse {
  // access content management system & e-commerce clients
  const cmsClient = await context.getApiClient("cms");
  const commerceClient = await context.getApiClient("commerce");
  
  // fetch data from the content management system
  const { id } = args;
  const { productIds, page } = await cmsClient.api.unified.getPage(id);

  // fetch products data from the e-commerce backend
  const products = await commerceClient.api.unified.getProducts(context, { ids: productIds });

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