The API Client

Introduction

Interacting with BigCommerce via the GraphQL Storefront API is a critical part of the Catalyst architecture, enabling dynamic data fetching and manipulation. To simplify this process, the @bigcommerce/catalyst-client package provides a convenient way to interact with the GraphQL API, wrapping the native fetch API for easier use. In this lesson, we will explore how to leverage this client to efficiently query and manage data within your Catalyst storefront.

Initializing the Client

The Catalyst API client must be initialized with the appropriate store-specific configuration details (such as the store hash and storefront token). With this config info, the client can then automatically take care of handling the HTTP request details for all GraphQL calls, including authentication.

You can see in client/index.ts that this initialization is done automatically by the main Catalyst project codebase.

The Standard Client Pattern

Let’s look at a simple API client example from the built-in queries, from app/[locale]/(default)/cart/page-data.ts:

...
const CartPageQuery = graphql(
  `
    query CartPageQuery($cartId: String) {
      site {
        cart(entityId: $cartId) {
          entityId
          version
          currencyCode
          ...
        }
        checkout(entityId: $cartId) {
          ...
        }
      }
    }
  `,
  [
    PhysicalItemFragment,
    DigitalItemFragment,
    MoneyFieldsFragment,
    ...
  ],
);
export const getCart = async (variables: Variables) => {
  ...
  const { data } = await client.fetch({
    document: CartPageQuery,
    variables,
    ...
  });
  return data;
};

This common pattern performs several tasks:

• Defines a GraphQL string with the query syntax itself.
• Passes this GraphQL string to the function graphql (notice that GraphQL fragments are similarly passed to the same function, the results being passed as a second “dependencies” argument for any queries that use them.)
• Passes the GraphQL document returned from graphql, along with any relevant variables and options, to the client.
• Extracts data from the expected structure of the GraphQL response.

Customer Context

The GraphQL Storefront API supports providing the context of a registered BigCommerce customer in any given request, which can affect the data returned. This comes into play if the user has logged in with valid BigCommerce customer credentials. For example, if a customer belongs to a customer group with access to only certain categories or with custom pricing, this will be reflected in the product information returned by GraphQL. Server-side requests like those in Catalyst establish this context by including the customer access token originally obtained during login in a specialized header.

The Catalyst API client supports passing in a customerAccessToken config parameter and will take care of including the context in the HTTP request if it’s provided. The storefront’s authentication implementation also exposes a simple function for retrieving the access token from a logged-in user’s session: the function getSessionCustomerAccessToken in auth/index.ts.

From the cart example:

import { getSessionCustomerAccessToken } from '~/auth';
...
export const getCart = async (variables: Variables) => {
  const customerAccessToken = await getSessionCustomerAccessToken();
  const { data } = await client.fetch({
    document: CartPageQuery,
    variables,
    customerAccessToken,
    ...
  });
  ...
};

You can easily use these tools to provide the current customer’s context to your own queries. Since this is an optional parameter of the API client, you can be selective about which queries and mutations pass in a customer context and which ones don’t. If you’re confident that a certain query will not be affected by customer context, making the request anonymous is typically the best option for performance.

Resources

• GraphQL Storefront API