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 API Methods
• Using Unified Methods in custom extensions
• Orchestrating Data with API Methods

Adding New API Methods

To implement a new API method, you have to:

• On the Middleware side:
  • Create a new Middleware extension
  • Create a new API method
  • Register the new method in the extension
  • Register the extension in the integration configuration
• On the Storefront side:
  • Add a new module to the SDK configuration

1. Create a new Middleware extension in the /integrations/<integration>/extensions/myExtension.ts file.

import type { ApiClientExtension } from "@vue-storefront/middleware";

export const myExtension = {
  name: "myExtension",
  extendApiMethods: {},
} satisfies ApiClientExtension;

And export the extension in the /integrations/<integration>/extensions/index.ts file.

export * from "./unified";
export * from "./multistore";
+export * from "./myExtension";

2. Create a new API method in the /api/myExtension directory.

First, define the arguments and response types in the /api/myExtension/types.ts file.

export interface GetHomePageArgs {
  // your arguments
}

export interface GetHomePageResponse {
  // interface for the response
}

Then, implement an API method in the /api/myExtension/getHomepage.ts file.

import type { SapccIntegrationContext } from "@vsf-enterprise/sapcc-api";
import type { GetHomePageArgs, GetHomePageResponse } from "./types";

export async function getHomepage(
  context: SapccIntegrationContext,
  args: GetHomePageArgs
): Promise<GetHomePageResponse> {
  // your implementation
}

And export the method in the /api/myExtension/index.ts file.

export * from "./getHomepage";

3. Create a new Middleware extension in the apps/storefront-middleware/integrations/<integration>/extensions directory and register custom API method.

import type { ApiClientExtension } from "@vue-storefront/middleware";
+import { getHomepage } from "../../../api/myExtension";

export const myExtension = {
  name: "myExtension",
  extendApiMethods: {
+   getHomepage,
  },
} satisfies ApiClientExtension;

import type { ApiClientExtension } from "@vue-storefront/middleware";

export const myExtension = {
  name: "myExtension",
  extendApiMethods: {
    getHomepage: async (context, args) => {
      // your implementation
    },
  },
} satisfies ApiClientExtension;

4. Export the type of the endpoints, to use them later in the SDK configuration.

import { WithoutContext } from "@vue-storefront/middleware";
-import { unifiedApiExtension } from "./extensions";
+import { unifiedApiExtension, myExtension } from "./extensions";

export type UnifiedApiExtension = typeof unifiedApiExtension;
export type UnifiedEndpoints = WithoutContext<UnifiedApiExtension["extendApiMethods"]>;

+export type MyExtension = typeof myExtension;
+export type MyExtensionEndpoints = WithoutContext<MyExtension["extendApiMethods"]>;

import { WithoutContext } from "@vue-storefront/middleware";
import { unifiedApiExtension, myExtension } from "./extensions";

export type UnifiedApiExtension = typeof unifiedApiExtension;
export type UnifiedEndpoints = WithoutContext<UnifiedApiExtension["extendApiMethods"]>;

export type MyExtension = typeof myExtension;
export type MyExtensionEndpoints = WithoutContext<MyExtension["extendApiMethods"]>;
+export * from "../../api/myExtension/types";

5. Register the extension in the integration config file.

+ import { myExtension } from "./extensions";

export const config = {
  // ...
  extensions: (extensions: ApiClientExtension[]) => [
    ...extensions,
    unifiedApiExtension,
    ...(IS_MULTISTORE_ENABLED ? [multistoreExtension] : []),
+   myExtension,
  ],
} satisfies Integration<MiddlewareConfig>;

6. Export MyExtensionEndpoints type from the apps/storefront-middleware/ app.

+ export type { MyExtensionEndpoints } from "./integrations/<integration>/types";

7. Finally, register a new SDK module with the MyExtensionEndpoints type under a custom namespace in the SDK configuration.

• In Nuxt go to apps/storefront-unified-nuxt/sdk.config.ts file.
• In Next.js go to apps/storefront-unified-nextjs/sdk/sdk.config.ts file.

-import type { UnifiedEndpoints } from 'storefront-middleware/types';
+import type { UnifiedEndpoints, MyExtensionEndpoints } from 'storefront-middleware/types';

export const { getSdk } = createSdk(
  options,
  ({ buildModule, middlewareModule, middlewareUrl, getRequestHeaders }) => ({
    unified: buildModule(middlewareModule<UnifiedEndpoints>, {
      apiUrl: `${middlewareUrl}/commerce`,
      defaultRequestConfig: {
        headers: getRequestHeaders(),
      },
    }),
+   myExtension: buildModule(middlewareModule<MyExtensionEndpoints>, {
+     apiUrl: `${middlewareUrl}/commerce`,
+     defaultRequestConfig: {
+       headers: getRequestHeaders(),
+     },
    }),
    cms: buildModule(contentfulModule, {
      apiUrl: `${middlewareUrl}/cntf`,
    }),
  })
);

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

// Storefront project
const { data } = sdk.myExtension.getHomepage({
  /* args */
});

Using Unified Methods in Custom Extensions

When creating a custom extension, 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 methods.getProductDetails(context, args);

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

Orchestrating Data

Data Orchestration 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",
      //...
    },
    // ...
  },
};