@shopware/api-client

shopware/frontends - api-client

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

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 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 {
  operationPaths,
  operations,
  components,
} from "@shopware/api-client/api-types";
// or (specific version):
import {
  operationPaths,
  operations,
  components,
} from "@shopware/api-client/api-types/apiTypes-6.4.20.0";
// or your types generated by @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"),
  apiType: "store-api",
  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>;

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",
  });
}

Links

• 📘 Documentation

• 👥 Community Slack (#shopware-frontends channel)

Changelog

Full changelog for stable version is available here

Latest changes: 0.0.0-canary-20230710115753

Patch Changes

• #303 aeb639a Thanks @patzick! - Improved linting in packages. Types should be more reliable