Data Fetching

Learn about implementing data fetching requirements in your React components.

In client-side applications, data fetching generally requires a lot of boilerplate code around implementation, state management, data normalization, etc. Customizations use the Merchant Center API to connect to Composable Commerce APIs.

To make it easier to connect to Composable Commerce APIs, we provide some pre-configured HTTP clients for both GraphQL and REST APIs.

GraphQL HTTP client

Composable Commerce APIs and the Merchant Center have first-class support for GraphQL. We strongly recommend building your customization using GraphQL whenever possible.

Customizations provide a pre-configured Apollo GraphQL Client to perform requests to the GraphQL APIs.

You can create a custom instance of the Apollo Client using the createApolloClient function.

Using React hooks

The preferred way of fetching data in a React component is to use React hooks.

The Apollo Client provides some React hooks to query data and mutate data.

Using the hooks in your React component is as simple as this:

channels.jsJavaScript

import { useQuery } from '@apollo/client/react';
import { GRAPHQL_TARGETS } from '@commercetools-frontend/constants';

const Channels = (props) => {
  const { data } = useQuery(FetchChannelsQuery, {
    context: {
      target: GRAPHQL_TARGETS.COMMERCETOOLS_PLATFORM,
    },
  });

  return <div>{/* Do something with `data` */}</div>;
};

In the preceding example, we define the context.target which configures the GraphQL target for the Merchant Center API.

The available GraphQL targets are exposed as a GRAPHQL_TARGETS constant in the @commercetools-frontend/constants package.

Using GraphQL documents

Inside each customization, you define your queries and mutations in dedicated .graphql files that you can import in your component file.

Using .graphql files is a great way to co-locate your data requirements next to your React component. Furthermore, you can leverage these files to improve the developer experience with editor syntax highlighting, linting, code generation, etc.

Let's create one:

fetch-channels.ctp.graphqlgraphql

query FetchChannels {
  channels {
    total
    count
    offset
    results {
      id
      key
      roles
      nameAllLocales {
        locale
        value
      }
    }
  }
}

And import it from the React component file:

import FetchChannelsQuery from './fetch-channels.ctp.graphql';

Error handling

We need to handle situations where requests may fail (network errors, schema validation errors, etc.).

The Apollo Client hooks provide an error object that we can use in our component to handle failures.

For example, we can render a content notification error instead of rendering the component.

channels.jsJavaScript

import { useQuery } from '@apollo/client/react';
import { GRAPHQL_TARGETS } from '@commercetools-frontend/constants';
import { ContentNotification } from '@commercetools-uikit/notifications';
import Text from '@commercetools-uikit/text';

const Channels = (props) => {
  const { data, error } = useQuery(FetchChannelsQuery, {
    context: {
      target: GRAPHQL_TARGETS.COMMERCETOOLS_PLATFORM,
    },
  });

  if (error) {
    return (
      <ContentNotification type="error">
        <Text.Body>{getErrorMessage(error)}</Text.Body>
      </ContentNotification>
    );
  }

  return <div>{/* Do something with `data` */}</div>;
};

For more information about using the error from Apollo Client, see Error handling.

In our case we just want to print the error.graphQLErrors. We can attempt to do that by implementing a helper function like this:

channels.jsJavaScript

const getErrorMessage = (error) =>
  error.graphQLErrors?.map((e) => e.message).join('\n') || error.message;

REST HTTP client

Some endpoints or APIs might not be available as GraphQL but as a standard HTTP REST endpoint instead.

We provide a pre-configured declarative fetching library @commercetools-frontend/sdk, which builds on top of the JS SDK client and Redux

The SDK library is built using Redux actions. This means that you dispatch an action describing the request and the library takes care of handling the request.

channels.jsJavaScript

import { useAsyncDispatch, actions } from '@commercetools-frontend/sdk';
import { MC_API_PROXY_TARGETS } from '@commercetools-frontend/constants';

const Channels = (props) => {
  const dispatch = useAsyncDispatch();
  useEffect(() => {
    async function execute() {
      try {
        const result = await dispatch(
          actions.get({
            mcApiProxyTarget: MC_API_PROXY_TARGETS.COMMERCETOOLS_PLATFORM,
            service: 'channels',
          });
        );
        // Update state with `result`
      } catch (error) {
        // Update state with `error`
      }
    }
    execute();
  }, [dispatch])

  return (
    <div>
      {/* Do something with the state */}
    </div>
  );
};

We define the mcApiProxyTarget, which is how you configure the proxy target for the Merchant Center API.

The available proxy targets are exposed as a MC_API_PROXY_TARGETS constant in the @commercetools-frontend/constants package.

The SDK library does not include features like data normalization, caching, etc. You will need to build these on your own.

Custom HTTP client

By default, we provide pre-configured HTTP clients for GraphQL and REST API requests.

However, you could use any other HTTP client of your choice, for example, Fetch, Axios, Stale-While-Revalidate (SWR), etc. If you use another HTTP client, you need to configure these clients on your own. In particular, you'll need to specify the required HTTP headers that should be sent with every request.

To make it easier to configure your HTTP client with the necessary HTTP headers, we provide some dedicated utility functions, such as executeHttpClientRequest.

Example using Fetch

The following example uses the Fetch API.

import createHttpUserAgent from '@commercetools/http-user-agent';
import {
  buildApiUrl,
  executeHttpClientRequest,
} from '@commercetools-frontend/application-shell';

const userAgent = createHttpUserAgent({
  name: 'fetch-client',
  version: '1.0.0',
  libraryName: window.app.applicationName,
  contactEmail: 'support@my-company.com',
});

const fetcher = async (url, config = {}) => {
  const data = await executeHttpClientRequest(
    async (options) => {
      const res = await fetch(buildApiUrl(url), options);
      const data = await res.json();
      return {
        data,
        statusCode: res.status,
        getHeader: (key) => res.headers.get(key),
      };
    },
    { userAgent, headers: config.headers }
  );
  return data;
};

const Channels = () => {
  useEffect(() => {
    async function execute() {
      try {
        const result = await fetcher('/proxy/ctp/channels');
        // Update state with `result`
      } catch (error) {
        // Update state with `error`
      }
    }
    execute();
  }, []);
  // ...
};

Example using Axios

The following example uses the Axios HTTP client.

import axios from 'axios';
import createHttpUserAgent from '@commercetools/http-user-agent';
import {
  buildApiUrl,
  executeHttpClientRequest,
} from '@commercetools-frontend/application-shell';

const userAgent = createHttpUserAgent({
  name: 'axios-client',
  version: '1.0.0',
  libraryName: window.app.applicationName,
  contactEmail: 'support@my-company.com',
});

const fetcher = async (url, config = {}) => {
  const data = await executeHttpClientRequest(
    async (options) => {
      const res = await axios(buildApiUrl(url), {
        ...config,
        headers: options.headers,
        withCredentials: options.credentials === 'include',
      });
      return {
        data: res.data,
        statusCode: res.status,
        getHeader: (key) => res.headers[key],
      };
    },
    { userAgent, headers: config.headers }
  );
  return data;
};

const Channels = () => {
  useEffect(() => {
    async function execute() {
      try {
        const result = await fetcher('/proxy/ctp/channels');
        // Update state with `result`
      } catch (error) {
        // Update state with `error`
      }
    }
    execute();
  }, []);
  // ...
};

Example using SWR

The following example uses the SWR React hook.

import useSWR from 'swr';
import createHttpUserAgent from '@commercetools/http-user-agent';
import {
  buildApiUrl,
  executeHttpClientRequest,
} from '@commercetools-frontend/application-shell';

const userAgent = createHttpUserAgent({
  name: 'swr-client',
  version: '1.0.0',
  libraryName: window.app.applicationName,
  contactEmail: 'support@my-company.com',
});

const fetcher = async (url, config = {}) => {
  const data = await executeHttpClientRequest(
    async (options) => {
      const res = await fetch(buildApiUrl(url), options);
      const data = await res.json();
      return {
        data,
        statusCode: res.status,
        getHeader: (key) => res.headers.get(key),
      };
    },
    { userAgent, headers: config.headers }
  );
  return data;
};

const Channels = () => {
  const { data, error } = useSWR('/proxy/ctp/channels', fetcher);
  // ...
};

Example using Ky

The following example uses the Ky HTTP client.

import ky from 'ky';
import createHttpUserAgent from '@commercetools/http-user-agent';
import {
  buildApiUrl,
  executeHttpClientRequest,
} from '@commercetools-frontend/application-shell';

const userAgent = createHttpUserAgent({
  name: 'ky-client',
  version: '1.0.0',
  libraryName: window.app.applicationName,
  contactEmail: 'support@my-company.com',
});

const fetcher = async (url, config = {}) => {
  const data = await executeHttpClientRequest(
    async (options) => {
      const res = await ky(buildApiUrl(url), options);
      const data = await res.json();
      return {
        data,
        statusCode: res.statusCode,
        getHeader: (key) => res.headers.get(key),
      };
    },
    { userAgent, headers: config.headers }
  );
  return data;
};

const Channels = () => {
  useEffect(() => {
    async function execute() {
      try {
        const result = await fetcher('/proxy/ctp/channels');
        // Update state with `result`
      } catch (error) {
        // Update state with `error`
      }
    }
    execute();
  }, []);
  // ...
};

Advanced usage

Using Connector Hooks

As your data requirements grow, for example, by having multiple queries and mutations in a React component, or using the same query in multiple components, you should consider extracting your queries into separate reusable hooks to help with organization and maintainability.

We recommend extracting the logic into what we call connector hooks.

A connector hook is a React hook that implements most of the data requirements (queries and mutations) specific to the use cases where the data should be used.

For example, we can extract the fetching of Channels into a connector hook named useChannelsFetcher. This hook can be put into a file named use-channels-connector.js.

use-channels-connector.jsJavaScript

import { useQuery } from '@apollo/client/react';
import { GRAPHQL_TARGETS } from '@commercetools-frontend/constants';

export const useChannelsFetcher = () => {
  const { data, error, loading } = useQuery(FetchChannelsQuery, {
    context: {
      target: GRAPHQL_TARGETS.COMMERCETOOLS_PLATFORM,
    },
  });

  return {
    channels: data?.channels,
    error,
    loading,
  };
};

Note that the use-channels-connector.js file can contain multiple connector hooks. For example useChannelsFetcher, useChannelsUpdater, useChannelsCreator, and so on.

We would then use our connector hook in the Channels component instead of directly using the Apollo Client hooks. Therefore, there is less code in the React component as most of the logic and configuration is abstracted away in the connector hook.

channels.jsJavaScript

import { ContentNotification } from '@commercetools-uikit/notifications';
import Text from '@commercetools-uikit/text';
import { useChannelsFetcher } from '../../hooks/use-channels-connector';

const Channels = (props) => {
  const { channels, error } = useChannelsFetcher();

  if (error) {
    return (
      <ContentNotification type="error">
        <Text.Body>{getErrorMessage(error)}</Text.Body>
      </ContentNotification>
    );
  }

  return <div>{/* Do something with `channels` */}</div>;
};

Connecting to an external API

If your customization needs to connect to an external API, in addition to the Composable Commerce APIs, the HTTP client has to be reconfigured to connect to the /proxy/forward-to endpoint with the appropriate headers.

When using the Apollo Client, you need to pass some configuration options to the context object.

The @commercetools-frontend/application-shell package exposes a createApolloContextForProxyForwardTo to construct a predefined context object specific to the /proxy/forward-to.

import {
  createApolloContextForProxyForwardTo,
  useMcQuery,
} from '@commercetools-frontend/application-shell';
import Text from '@commercetools-uikit/text';
import HelloWorldQuery from './hello-world.graphql';

const HelloWorld = () => {
  const { loading, data, error } = useMcQuery(HelloWorldQuery, {
    context: createApolloContextForProxyForwardTo({
      uri: 'https://my-custom-app.com/graphql',
    }),
  });

  if (loading) return 'Loading...';
  if (error) return `Error! ${error.message}`;
  return <Text.Headline as="h1">{data.title}</Text.Headline>;
};

Similarly, when using a custom HTTP client, you can pass an additional configuration object forwardToConfig.

import createHttpUserAgent from '@commercetools/http-user-agent';
import {
  buildApiUrl,
  executeHttpClientRequest,
} from '@commercetools-frontend/application-shell';

const fetcherForwardTo = async (targetUrl, config = {}) => {
  const data = await executeHttpClientRequest(
    async (options) => {
      const res = await fetch(buildApiUrl('/proxy/forward-to'), options);
      const data = res.json();
      return {
        data,
        statusCode: res.status,
        getHeader: (key) => res.headers.get(key),
      };
    },
    {
      userAgent,
      headers: config.headers,
      forwardToConfig: {
        uri: targetUrl,
      },
    }
  );
  return data;
};

const HelloWorld = () => {
  useEffect(() => {
    async function execute() {
      try {
        const result = await fetcherForwardTo('https://my-custom-app.com/api');
        // Update state with `result`
      } catch (error) {
        // Update state with `error`
      }
    }
    execute();
  }, []);
  // ...
};

Calling REST APIs inside your GraphQL queries

This feature is available from version 21.10.0 onwards.

If you want to keep using the benefits of GraphQL (and Apollo Client) but for REST APIs, you can use the Apollo REST Link as an opt-in feature to the GraphQL HTTP client.

You can follow the instructions of the Apollo REST Link to set it up and configure the GraphQL document to send a request via the @rest directive.

To use the Apollo REST Link with the built-in GraphQL HTTP client, you need to create a new Apollo Client instance using the createApolloClient utility function.

An example of fetching Channels using the @rest directive:

channels.jsJavaScript

import { useMcQuery } from '@commercetools-frontend/application-shell';
import { useApplicationContext } from '@commercetools-frontend/application-shell-connectors';
import { MC_API_PROXY_TARGETS } from '@commercetools-frontend/constants';
import {
  usePaginationState,
  useDataTableSortingState,
} from '@commercetools-uikit/hooks';
import { FetchChannelsQuery } from './fetch-channels.ctp.graphql';

const Channels = (props) => {
  const projectKey = useApplicationContext((context) => context.project.key);
  const { page, perPage } = usePaginationState();
  const tableSorting = useDataTableSortingState({ key: 'key', order: 'asc' });
  const searchParams = new URLSearchParams({
    limit: perPage.value,
    offset: (page.value - 1) * perPage.value,
    sort: `${tableSorting.value.key} ${tableSorting.value.order}`,
  });
  const { data, error, loading } = useMcQuery(FetchChannelsQuery, {
    fetchPolicy: 'cache-and-network',
    variables: {
      endpoint: `/proxy/${
        MC_API_PROXY_TARGETS.COMMERCETOOLS_PLATFORM
      }/${projectKey}/channels?${searchParams.toString()}`,
    },
    context: {
      skipGraphQlTargetCheck: true,
    },
  });

  if (error) {
    return (
      <ContentNotification type="error">
        <Text.Body>{getErrorMessage(error)}</Text.Body>
      </ContentNotification>
    );
  }

  return <div>{/* Do something with `channels` */}</div>;
};

The related GraphQL document:

fetch-channels.ctp.graphqlgraphql

query FetchChannelsRest($endpoint: String!) {
  channels @rest(type: "ChannelQueryResult", path: $endpoint) {
    total
    count
    offset
    results @type(name: "Channel") {
      id
      key
      nameAllLocales @type(name: "LocalizedString") {
        locale
        value
      }
    }
  }
}

Please note:

Types and nested types require you to define the __typename via @rest(type: "") or @type(name: "").
The endpoint is passed as a variable and should point to the Merchant Center API proxy target endpoint.

For LocalizedString fields such as name (in the REST API) you should use the GraphQL naming convention nameAllLocales. However, you also need to instruct the Apollo REST Link to correctly transform the shape of the field. You can do that using the responseTransformer function.

import { applyTransformedLocalizedStrings } from '@commercetools-frontend/l10n';

const restLink = new RestLink({
  uri: getMcApiUrl(),
  // https://www.apollographql.com/docs/react/api/link/apollo-link-rest/#response-transforming
  responseTransformer: async (response, typeName) => {
    const data = await response.json();

    switch (typeName) {
      case 'ChannelQueryResult':
        return {
          ...data,
          results: data.results.map((channel) =>
            applyTransformedLocalizedStrings(channel, [
              {
                from: 'name',
                to: 'nameAllLocales',
              },
            ])
          ),
        };
      default:
        return data;
    }
  },
});

Using file uploads

If you need to support file uploads, you can use FormData. The FormData object can then be sent as the HTTP request body.

It is important to properly configure the Content-Type HTTP header, which usually must be set to multipart/form-data. However, you also need to provide a boundary directive.

We recommend that you omit the Content-Type HTTP header in the request and let the browser correctly infer it.

When using the @commercetools-frontend/sdk package, you need to explicitly unset the Content-Type HTTP header by passing null as value.

{
  'Content-Type': null
}