@shopware/api-client

shopware/frontends - api-client

Dynamic and fully typed API Client for Shopware 6. Usable in any JavaScript and TypeScript project. You can use types generated from your custom API instance to have autocompletion and type safety.

To generate your own types use @shopware/api-gen CLI.

Setup

Install npm package:

# Using pnpm
pnpm add @shopware/api-client

# Using yarn
yarn add @shopware/api-client

# Using npm
npm i @shopware/api-client

Recommended practice is to create a separate module file. For example src/apiClient.ts, and import it whenever you need to use API Client.

import { createAPIClient } from "@shopware/api-client";

// You can pick types of your current API version, the default one:
import type {
  operationPaths,
  operations,
  components,
} from "@shopware/api-client/api-types";
// or - RECOMMENDED - your types generated by [@shopware/api-gen](https://www.npmjs.com/package/@shopware/api-gen) CLI:
import { operationPaths, operations, components } from "./apiTypes";

// you can pick cookies library of your choice
import Cookies from "js-cookie";

export const apiClient = createAPIClient<operations, operationPaths>({
  baseURL: "https://demo-frontends.shopware.store/store-api",
  accessToken: "SWSCBHFSNTVMAWNZDNFKSHLAYW",
  contextToken: Cookies.get("sw-context-token"),
  onContextChanged(newContextToken) {
    Cookies.set("sw-context-token", newContextToken, {
      expires: 365, // days
      path: "/",
      sameSite: "lax",
    });
  },
});

// reimport schemas to use it in application
export type ApiSchemas = components["schemas"];
// reimport operations request parameters to use it in application
export type ApiRequestParams<OPERATION_NAME extends keyof operations> =
  RequestParameters<OPERATION_NAME, operations>;
// reimport operations return types to use it in application
export type ApiReturnType<OPERATION_NAME extends keyof operations> =
  RequestReturnType<OPERATION_NAME, operations>;

Admin API client setup

The setup works the same way as creteAPIClient function, with few differences

credentials (optional) - Quick scripting or token-based authentication

We provide optional credentials parameter to createAdminAPIClient. Which allows you to use authentication type of your choice whenever you wish to create connection to any endpoint.

Example:

import type {
  operationPaths,
  operations,
  components,
} from "@shopware/api-client/admin-api-types"; // we take default admin api types from different directory than store-api - use your own types by generating schema with @shopware/api-gen CLI

const adminApiClient = createAdminAPIClient<operations, operationPaths>({
  baseURL: `${process.env.SHOP_URL}/api`,
  credentials: {
    grant_type: "password",
    client_id: "administration",
    scopes: "write",
    username: process.env.SHOP_ADMIN_USERNAME,
    password: process.env.SHOP_ADMIN_PASSWORD,
  },
  // credentials: { // or token-based example
  //   grant_type: "client_credentials",
  //   client_id: "administration",
  //   client_secret: process.env.SHOP_ADMIN_TOKEN,
  // },
});

await adminApiClient.invoke(...); // invoke defined endpoint

sessionData (optional) - Persistent authentication

This parameter is used to store session data in cookies (or other place you want to store it), so you can keep your session persistent.

You can combine this option with credentials property.

// example adminApiClient.ts file
import { createAdminAPIClient } from "@shopware/api-client"; // we use different function to create admin api client

import {
  RequestParameters,
  RequestReturnType,
  createAdminAPIClient,
} from "@shopware/api-client";
import type {
  operationPaths,
  operations,
  components,
} from "@shopware/api-client/admin-api-types"; // we take default admin api types from different directory than store-api
import Cookies from "js-cookie";

export const adminApiClient = createAdminAPIClient<operations, operationPaths>({
  baseURL: "https://demo-frontends.shopware.store/api",
  sessionData: JSON.parse(Cookies.get("sw-admin-session-data") || "{}"),
  onAuthChange(sessionData) {
    Cookies.set("sw-admin-session-data", JSON.stringify(sessionData), {
      expires: 1, // days
      path: "/",
      sameSite: "lax",
    });
  },
});

export type AdminApiSchemas = components["schemas"];
export type AdminApiRequestParams<OPERATION_NAME extends keyof operations> =
  RequestParameters<OPERATION_NAME, operations>;
export type AdminApiReturnType<OPERATION_NAME extends keyof operations> =
  RequestReturnType<OPERATION_NAME, operations>;

the rest works the same as store-api client.

Basic usage

Take a look at example project using API Client.

Simple invocation

import { apiClient, ApiReturnType } from "./apiClient";

// could be reactive value, you can use ApiReturnType to type it properly
let productsResponse: ApiReturnType<"readProduct">;

async function loadProducts() {
  productsResponse = await apiClient.invoke("readProduct post /product", {
    limit: 2,
  });
}

Predefining methods

If you prefer to add another layer of abstraction you can use created previously types to define your own concept of methods.

// add for example into apiClient.ts file
const readNavigation = (params: ApiRequestParams<"readNavigation">) =>
  apiClient.invoke(
    "readNavigation post /navigation/{activeId}/{rootId} sw-include-seo-urls",
    {
      depth: 2,
      ...params,
    },
  );

// in another file you can use it, and depth property will be set to 2 by default
import { readNavigation } from "./apiClient";

async function loadMainNavigation() {
  const navigation = await readNavigation({
    activeId: "main-navigation",
    rootId: "main-navigation",
  });
}

Error handling

Client is throwing ApiClientError with detailed information returned from the API. It will display clear message in the console or you can access details property to get raw information from the response.

import { ApiClientError } from "@shopware/api-client";

try {
  // ... your request
} catch (error) {
  if (error instanceof ApiClientError) {
    console.error(error); // This prints message summary
    console.error("Details:", error.details); // Raw response from API
  } else {
    console.error("==>", error); // Another type of error, not recognized by API client
  }
}

Links

• 📘 Documentation

• 👥 Community Slack (#shopware-frontends channel)

Changelog

Full changelog for stable version is available here

Latest changes: 0.0.0-canary-20240318143602

Minor Changes

• #560 9643e56 Thanks @patzick! - [createAdminAPIClient] ability to pass optional field credentials to be used as authentication method before invoking any Admin API endpoint.

• #639 d60d062 Thanks @patzick! - Management of defaultHeaders. You can now set them on apiClient init or runtime.

  const apiClient = createApiClient({
    ...,
    defaultHeaders: {
      'sw-language-id': 'my-id',
    },
  });
  
  console.log('Debug default headers:', apiClient.defaultHeaders);
  
  // Change header runtime
  apiClient.defaultHeaders['sw-language-id'] = 'my-new-id';
  
  // Remove header runtime
  apiClient.defaultHeaders['sw-language-id'] = "";
  
  // Change multiple headers runtime
  apiClient.defaultHeaders.apply({
    'sw-language-id': 'another-id',
    'sw-currency-id': 'currency-id',
  })
  

Patch Changes

• #567 1583a7a Thanks @patzick! - Export default API types to be compatible with the bundler mode resolution in tsconfig

• #557 97d2859 Thanks @patzick! - Added Accept: application/json default header to get only JSON responses.

• 89a97a4 Thanks @patzick! - fix default types