In order to use updates made to this fork @edekadigital/fsxa-api a new version must be published to Artifactory.
Make sure you are working with Artifactory as npm registry, not the public npm registry, by creating a .npmrc file.
echo "registry=https://repo.edeka.dev/artifactory/api/npm/digitales-npm/" > .npmrc
Make sure you are authenticated against Artifactory with the user digitales-npm. The password is stored securely in 1Password.
npm login
Make sure you are on the master branch and create a new build.
git checkout master
npm run build
Create a new version (using semver).
npm version x.y.z
Push the automatically generated commit with changes to package.json and the new tag to the git origin (Github).
git push
git push --tags
Publish the new version to Artifactory.
npm publish
The FSXA-API is an interface handling data coming from the FirstSpirit CaaS and the Navigation Service. The data is processed and transformed to suit the needs of the FSXA-Pattern-Library.
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.
FSXA-API is a product of e-Spirit AG, Dortmund, Germany. The FSXA-API is subject to the Apache-2.0 license.
In this section all available methods will be explained using examples.
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"
}
}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
)The configuration of the FSXA-API can be set via a method.
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 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"
}
}
})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()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()Returns the build CaaS url when mode is set to remote:
Returns an empty string when mode is set to proxy.
Example:
fsxaApi.buildCaaSUrl()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()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-parameter. For more information please refer to the restheart documentation.
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}]}
)Returns the matching CaaS data entries.
Expects as input parameter an array of filters and a language abbreviation. Optionally a page number, page size and additional parameters can be passed.
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. However, we do not want the identifier to appear:
fsxaApi.fetchByFilter(
[
{
field: "fsType",
operator: ComparisonQueryOperatorEnum.EQUALS,
value: "Example"
}
],
"en",
2,
50,
{"keys": {"identifier": 0}}
)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")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.
These operators can also be found in the MongoDB Documentation
| Enum | Operation |
|---|---|
| LogicalQueryOperatorEnum.AND | $and |
| LogicalQueryOperatorEnum.NOT | $not |
| LogicalQueryOperatorEnum.NOR | $nor |
| LogicalQueryOperatorEnum.OR | $or |
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 |
These operators can also be found in the MongoDB Documentation
| Enum | Operation |
|---|---|
| ArrayQueryOperatorEnum.ALL | $all |
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.