Sulu Headless API Client

This module provides a Promise based way to work with the SuluHeadlessBundle JSON API.

Installation

# With npm
npm install sulu-headless-api-client

# Or yarn
yarn add sulu-headless-api-client

Basic usage

import Client from 'sulu-headless-api-client';

// Create client
const client = new Client();

// Get page data
client
    .getPageByPath(window.location.pathname)
    .then((page) => {
        // Do something with page data...
    });

Advanced usage

import Client from 'sulu-headless-api-client';
import sortNavigation from './helpers/sortNavigation';

// Create client
const navigationClient = new Client({
    baseUrl: process.env.SULU_BASE_URL,
    removeEmbedded: true,
    onResponse: (response) => sortNavigation(response),
});

// Get navigation data
navigationClient
    .getNavigationByKey('main', {
        depth: 3,
        excerpt: true,
        flat: true,
    })
    .then((navigation) => {
        // Do something with navigation data...
    });

Or with Axios.

import Client from 'sulu-headless-api-client';
import axios from 'axios';
import sortNavigation from './helpers/sortNavigation';

// Create client
const navigationClient = new Client({
    baseUrl: process.env.SULU_BASE_URL,
    fetchClient: axios,
    fetchOptions: {
        transformResponse: (response) => sortNavigation(response),
    },
    removeEmbedded: true,
});

// Get navigation data
navigationClient
    .getNavigationByKey('main', {
        depth: 3,
        excerpt: true,
        flat: true,
    })
    .then((navigation) => {
        // Do something with navigation data...
    });

Non-browser environments

By default, Client is intended to work in a browser environment. For non-browser environments, like Static Site Generation with Next.js or Astro, you need to opt-out from using the default baseUrl and fetchClient which rely on the window object. For example:

import Client from 'sulu-headless-api-client';

// Create client
const client = new Client({
    baseUrl: process.env.SULU_BASE_URL,
    fetchClient: fetch,
});

Error handling

import Client from 'sulu-headless-api-client';
import handleError from './helpers/handleError';
import handleSearchError from './helpers/handleSearchError';

// Client wide
const client = new Client({
    onError: (error) => handleError(error),
});

// Or per method
client
    .getPageByPath(window.location.pathname)
    .then((page) => {
        // Do something with page data...
    })
    .catch((error) => handleError(error));

client
    .search(query)
    .then((hits) => {
        // Do something with hits...
    })
    .catch((error) => handleSearchError(error));

Constructor

const client = new Client(options)

Creates a client.

Parameters

| Parameter | Required? | Type | Default | Description | |:-------------------------|:----------|:--------------------|:---------------------------|:----------------------------------------------------------------------| | options | No | Object | {} | The options for the client. | | options.basePath | No | String | /api | The base path of the API. | | options.baseUrl | No | String | window.location.pathname | The base URL of the API. | | options.fetchClient | No | Function | fetch.bind(window) | The fetch client to use. Tested with fetch and axios. | | options.fetchOptions | No | Object | {} | The options for the fetch client. | | options.locale | No | String | '' | The locale for every request. | | options.onError | No | Function(Error) | () => {} | The function to call on error. | | options.onResponse | No | Function(Reponse) | (r) => r | The function to call on response. | | options.removeEmbedded | No | Boolean | false | Whether to remove the _embedded layer from the response if present. |

Instance methods

client.getPageByPath(path)

Retrieves page data from the given path.

Parameters

| Parameter | Required? | Type | Default | Description | |:----------|:----------|:---------|:--------|:----------------------------------| | path | Yes | String | - | The path of the page to retrieve. |

Return value

A Promise that resolves to the page data.

client.getNavigationByKey(key[, params])

Retrieves navigation data with the given key and optional query parameters.

Parameters

| Parameter | Required? | Type | Default | Description | |:-----------------|:----------|:----------|:--------|:-------------------------------------------| | key | Yes | String | - | The key of the navigation to retrieve. | | params | No | Object | - | The query parameters for the request. | | params.depth | No | Number | 1 | The maximum depth of the navigation. | | params.excerpt | No | Boolean | false | Whether to include excerpt data. | | params.flat | No | Boolean | false | Whether to return as list instead of tree. |

Return value

A Promise that resolves to the navigation data.

client.getSnippetByArea(area[, params])

Retrieves snippet data with the given area name and optional query parameters.

Parameters

| Parameter | Required? | Type | Default | Description | |:--------------------------|:----------|:----------|:--------|:------------------------------------------| | area | Yes | String | - | The name of the snippet area to retrieve. | | params | No | Object | - | The query parameters for the request. | | params.includeExtension | No | Boolean | false | Whether to include extension data. |

Return value

A Promise that resolves to the snippet area data.

client.search(query)

Performs a search with the given query.

Parameters

| Parameter | Required? | Type | Default | Description | |:----------|:----------|:---------|:--------|:------------------| | query | Yes | String | - | The search query. |

Return value

A Promise that resolves to the search results.

Testing

Run yarn test to fire up the Mockoon CLI mock API and run all Playwright tests. Don't worry, everything stops after testing has finished.

License

Licensed under MIT.