FSXA-API

The FSXA-API is an interface handling data coming from the FirstSpirit CaaS and the Navigation Service. The data is processed and transformed so that it can be used in any JavaScript project.

FSXA-API

About the FSXA

The FirstSpirit Experience Accelerator (FSXA) is the hybrid solution of a digital experience platform, combining a headless approach with enterprise capabilities. If you are interested in the FSXA check this Overview. You can order a demo online.

Experimental features

Features marked as experimental are subject to change as long as they remain in the experimental state. Breaking changes to experimental features are not reflected in major version changes.

Legal Notices

FSXA-API is a product of e-Spirit AG, Dortmund, Germany. The FSXA-API is subject to the Apache-2.0 license.

Methods

In this section all available methods will be explained using examples.

Constructor

To be able to use the FSXA-API, a new object must be created. How you create the object depends on how you want to use the FSXA-API.

If you want to use the information provided by the CaaS in your frontend, you have to use the proxy mode. If you want to use it in your server, you have to use the remote mode.

However, to have a fully running application, we recommend using the FSXA-API in your server as well as in your frontend.

In each case you have to specify the content mode, the configuration and optionally the log level.

The config mode can be preview or release. It depends on which information you want to get.
There is an enum to use these modes.
FSXAContentMode.PREVIEW for preview
FSXAContentMode.RELEASE for release

The configuration depends on which in which mode you want to run the FSXA-API.

If you want to use the remote mode, you have to specify all authorization keys:

{
    mode: "remote",
    config: {
            apiKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            navigationService: "https://your.navigation-service.url/navigation",
            caas: "https://your.caas.url",
            projectId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            tenantId: "your-tenant-id"
    }
}

You can also include remote projects if you want to use remote media.

Attention
Currently the FSXA-API can only work with the master language of the remote media project.

For this you can add another parameter called remotes to the config. This parameter expects an object, which requires a unique name as key and an object as value. This object must have two keys. On the one hand an id with the project id as the value and on the other the locale with the locale abbreviation. For example:

{
    mode: "remote",
    config: {
            apiKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            navigationService: "https://your.navigation-service.url/navigation",
            caas: "https://your.caas.url",
            projectId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            tenantId: "your-tenant-id",
            remotes: { "media": {"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "locale": "en_GB"} }
    }
}

If you want to use the proxy mode, you have to specify the baseURL:

{
    mode: 'proxy',
    baseUrl: 'http://localhost:3001/api'
}

Be aware that in the case of proxy mode the baseURL should point to a proxy server that knows and appends the apikey of the FirstSpirit CaaS.

The log level can be: 0 = Info 1 = Log 2 = Warning 3 = Error 4 = None. The default is set to 3.

Here is an example of how the FSXA-API could be used with an Express.js backend. Make sure you have cross-fetch, express, cors, lodash and of course fsxa-api installed.

require('cross-fetch/polyfill')
const express = require('express')
const { FSXAApi, FSXAContentMode } = require('fsxa-api')
const expressIntegration = require('fsxa-api/dist/lib/integrations/express').default
const cors = require('cors')

const app = express()

const remoteApi = new FSXAApi(
  FSXAContentMode.PREVIEW,
  {
    mode: 'remote',
    config: {
      apiKey: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
      navigationService: 'https://your.navigation-service.url/navigation',
      caas: 'https://your.caas.url',
      projectId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
      tenantId: 'your-tenant-id',
    },
  },
  3
)

app.use(cors())
app.use('/api', expressIntegration({ api: remoteApi }))

app.listen(3001, () => {
  console.log('Listening at http://localhost:3001')
})

Here is an example of the corresponding usage in a frontend application:

const fsxaApi = new FSXAApi(
  FSXAContentMode.PREVIEW,
  {
    mode: 'proxy',
    baseUrl: 'http://localhost:3001/api',
  },
  1
)

setConfiguration

The configuration of the FSXA-API can be set via a method.

The config data depends on which in which mode you want to run the FSXA-API.

If you want to use the remote mode, you have to specify all authorization keys:

{
    mode: "remote",
    config: {
            apiKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            navigationService: "https://your.navigation-service.url/navigation",
            caas: "https://your.caas.url",
            projectId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            tenantId: "your-tenant-id"
    }
}

If you want to use the proxy mode, you have to specify the baseURL:

{
    mode: 'proxy',
    baseUrl: 'http://localhost:3001/api'
}

Be aware that in the case of proxy mode the baseURL should point to a proxy server that knows and appends the apikey of the FirstSpirit CaaS.

Example:

fsxaApi.setConfiguration({
  FSXAContentMode.RELEASE,
  {
    mode: "remote",
        config: {
            apiKey: "xxxx-xxxx-xxxx-xxxx",
            navigationService: "https://your.navigation.service",
            caas: "https://your.caas.service",
            projectId: "xxx-xxxx-xxx",
            tenantId: "your-tentant-id"
        }
  }
})

config

Returns the current configuration when the mode is set to remote.
If the mode is set to proxy, this method returns null.

Example:

fsxaApi.config()

buildAuthorizationHeaders

Returns the build authorization header in the following format when mode is set to remote:

{
  authorization: 'apikey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"'
}

Returns an empty object when mode is set to proxy.

Example:

fsxaApi.buildAuthorizationHeaders()

buildCaaSURL

Expects an optional parameter remoteProjectId. If passed, the CaaS Url will be built with it instead of the default project id.

Returns the build CaaS url when mode is set to remote:

Returns an empty string when mode is set to proxy.

Example:

fsxaApi.buildCaaSUrl()

buildNavigationServiceUrl

Returns the build navigation-service url when mode is set to remote:

Returns an empty string when mode is set to proxy.

Example:

fsxaApi.buildNavigationServiceUrl()

fetchElement

Returns the corresponding CaaS data entry.

Expects as input parameter an id, which is described in CaaS as 'identifier' and a language abbreviation.
Optionally, additional parameters can be passed that will be appended to the CaaS-Url. Be aware that the response is not mapped if you pass the keys. For more information please refer to the restheart documentation.
Optionally, a remoteProject can be passed. If one is passed, the element will be fetched from this project instead of the default one.

In this example the additional parameters ensure that only the fields identifier and displayName are in the result set:

fsxaApi.fetchElement('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 'en-EN', {
  keys: [{ identifier: 1 }, { displayName: 1 }],
})

fetchByFilter

Returns the matching CaaS data entries.

Expects as input parameter an array of filters and a language abbreviation. Optionally a page number, page size, sort and additional parameters can be passed.
Optionally, a remoteProject can be passed. If one is passed, the element will be fetched from this project instead of the default one.

Several filter objects can be specified in the filter array, the results will then correspond to all specified filters.

One filter object must have a:
field which specifies the searched key,
operator which specifies the search operation,
value which specifies the value that is looked for.

More information to the filters

In this example we search for all elements with the fsType equals Example. We want the 2nd page with a maximum of 50 entries. The results should be sorted by fsType descending. However, we do not want the identifier to appear:

fsxaApi.fetchByFilter({
    filters: [
      {
        field: 'fsType',
        operator: ComparisonQueryOperatorEnum.EQUALS,
        value: 'Example',
      },
    ],
    locale: 'en',
    page: 2,
    pagesize: 50,
    additionalParams: { keys: { identifier: 0 } },
    sort: [{name:'fsType', order:'desc'}],
  }
)

The default sorting is by the id descending. Multisort is possible and the first sort param is prioritized over subsequent. The sorting is happening on the raw data.

fetchProjectProperties

Returns the project properties of the given language.

Expects as input parameter the language abbreviation.

ATTENTION: Works only with CaaSConnect module version 3 onwards.

Example:

fsxaApi.fetchProjectProperties('en_EN')

Filter

You can customize your queries in the fetchByFilter method with these operations. For more information please refer to the MongoDB documentation. Links are provided in each section.

Logical Query Operators

These operators can also be found in the MongoDB Documentation

Enum	Operation
LogicalQueryOperatorEnum.AND	$and
LogicalQueryOperatorEnum.NOT	$not
LogicalQueryOperatorEnum.NOR	$nor
LogicalQueryOperatorEnum.OR	$or

Comparison Query Operators

These operators can also be found in the MongoDB Documentation

Enum	Operation
LogicalQueryOperatorEnum.GREATER_THAN_EQUALS	$gte
LogicalQueryOperatorEnum.GREATER_THAN	$gt
LogicalQueryOperatorEnum.EQUALS	$eq
LogicalQueryOperatorEnum.IN	$in
LogicalQueryOperatorEnum.LESS_THAN	$lt
LogicalQueryOperatorEnum.LESS_THAN_EQUALS	$lte
LogicalQueryOperatorEnum.NOT_EQUALS	$ne
LogicalQueryOperatorEnum.NOT_IN	$nin

Array Query Operators

These operators can also be found in the MongoDB Documentation

Enum	Operation
ArrayQueryOperatorEnum.ALL	$all

Type Mapping

Input Components

This table gives an overview of the FirstSpirit input components, which could be defined in the "Form" tab of the FirstSpirit templates. Each input component has a (Java) data type, which has a representation in the CaaS. Those values are mapped to an interface of the fsxa-api.

FirstSpirit Input Component	CaaS Representation	FSXA-API Value
FS_CATALOG `Catalog<Catalog$Card>`	= `CaaSApi_FSCatalog` = `CaaSApi_Card[]`	`Section[]`
CMS_INPUT_CHECKBOX `Set<Option>`	= `CaaSApi_CMSInputCheckbox` = `CaaSApi_Option[]`	`Option[]`
CMS_INPUT_COMBOBOX `Option`	= `CaaSApi_CMSInputCombobox` = `CaaSApi_Option`	`Option`
FS_DATASET `DatasetContainer`	= `CaaSApi_FSDataset` = `CaaSApi_Dataset`	`Dataset`
CMS_INPUT_DATE `Date`	= `CaaSApi_CMSInputDate` = `string` (ISO_8601)	`Date`
CMS_INPUT_DOM `DomElement`	= `CaaSApi_CMSInputDOM` = `string` (FS-XML)	`RichTextElement[]`
CMS_INPUT_DOMTABLE `Table`	= `CaaSApi_CMSInputDOMTable` = `string` (FS-XML)	`RichTextElement[]`
CMS_INPUT_IMAGEMAP `MappingMedium`	= `CaaSApi_CMSImageMap` = `CaaSApi_CMSImageMap`	`ImageMap`
FS_INDEX `Index<Index$Record>`	= `CaaSApi_FSIndex` = `CaaSApi_Record[]`	`DataEntries[]`
CMS_INPUT_LINK `Link`	= `CaaSApi_CMSInputLink` = `Object`	`Link`
CMS_INPUT_LIST `Set<Option>`	= `CaaSApi_CMSInputList` = `CaaSApi_Option[]`	`Option[]`
CMS_INPUT_NUMBER `Number`	= `CaaSApi_CMSInputNumber` = `number`	`number`
CMS_INPUT_PERMISSION `Permissions`	= `CaaSApi_CMSInputPermission` = `CaaSAPI_PermissionActivity[][]`	`Permission`
CMS_INPUT_RADIOBUTTON `Option`	= `CaaSApi_CMSInputRadioButton` = `CaaSApi_Option`	`Option`
FS_REFERENCE `TargetReference`	= `CaaSApi_FSReference` = `CaaSApi_BaseRef \| CaaSApi_PageRefRef \| CaaSApi_GCARef \| CaaSApi_MediaRef`	`Page \| GCAPage \| Media \| DataEntry`
CMS_INPUT_TEXT `String`	= `CaaSApi_CMSInputText` = `string`	`string`
CMS_INPUT_TEXTAREA `String`	= `CaaSApi_CMSInputTextArea` = `string`	`string`
CMS_INPUT_TOGGLE `Boolean`	= `CaaSApi_CMSInputToggle` = `boolean`	`boolean`

Disclaimer

This document is provided for information purposes only. e-Spirit may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. e-Spirit specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.

FollowJack/fsxa-api

FSXA-API

About the FSXA

Experimental features

Legal Notices

Methods

Constructor

setConfiguration

config

buildAuthorizationHeaders

buildCaaSURL

buildNavigationServiceUrl

fetchElement

fetchByFilter

fetchProjectProperties

Filter

Logical Query Operators

Comparison Query Operators

Array Query Operators

Type Mapping

Input Components

Disclaimer