What is an Integration?

In Alokai, an integration that connects your storefront to a backend platform. It provides the data, logic, and methods to interact with your various services in a type-safe way.

This means that you don't have to worry about creating your own API calls to work a service's API. Instead, you can use the integration SDK to get the data you need.

Key Features

• Ready to use - You can use the SDK to interact with your backend without writing any API calls yourself
• Type-safe - The SDK is fully typed, so you can use it with confidence
• Customizable - You can extend the SDK and Middleware to add new methods, modify existing methods, and more
• Modular - You can use multiple integrations at once, and they won't interfere with each other

Architecture

Every integration consists of two parts:

1. An API Client that extends the Alokai middleware to add endpoints and logic for a specific service
2. An SDK Module that extends the Alokai SDK to provide methods for calling the middleware endpoints

You can learn more about how the SDK and Middleware work in their respective docs.

Using an Integration

Once you've configured your integration, you can use it in your storefronts through the SDK.

For example, if you wanted to fetch a product by its slug, it might look like this.

// Import the SDK from wherever it was initialized
import { sdk } from '~/sdk'

// Use a module method to fetch the product
const product = await sdk.commerce.getProduct({ slug: 'my-product' })

In this example, we've added a commerce integration to our storefront. It has a getProduct method that we can use to fetch a product by its slug. The SDK will then call the middleware endpoint to fetch the product from the backend.

The specific syntax may be different depending on the integration you're using, but the general idea is the same.

1. Configure the SDK and Middleware
2. Call a method from the SDK
3. product contains the data we need and is fully typed

If you're using our storefront, a lot of this e-commerce logic is already implemented in React hooks or Vue composables. This means you can cut down on boilerplate code and focus on customizing your storefront's UI and logic.

Customizing an Integration

Integrations contain an API Client and SDK module, so there are two places where you can customize them. Both the Alokai Middleware and SDK provide Extensions that allow you to do things like modify requests/responses, add new API methods, override existing methods, and more.

You can learn more about Middleware and SDK extensions in their respective docs.

Where to extend?

Since you can extend both the SDK and Middleware, you might be wondering where you should extend your integration. While it depends on your use cases, here are some general guidelines:

• If you want to add logic to modify requests/responses, try extending the Middleware to avoid sending additional code or unnecessary data to the client
• If you're adding new methods or modifying existing methods, you should extend the SDK