Using OnsDB tables in Ons API

Ons API primarily exposes data through Ons API models. In some cases, data that is available in OnsDB is not yet available through these models. For these situations, individual OnsDB tables can be added to an Ons API connector. This makes it possible to retrieve OnsDB table data through the existing Ons API connector, without having to run the separate OnsDB application for this purpose.

When to use OnsDB tables

We recommend using Ons API models whenever the required data is available through a model. Ons API models support the regular Ons API configuration options, including field selection and data minimization.

Use OnsDB tables only when the required data is not available through Ons API models.

Configuring OnsDB tables

OnsDB tables can be added to a connector version in the Ons API Dashboard.The configuration is similar to configuring Ons API models:

1. Open the connector version in the Ons API Dashboard.
2. Go to the tab for OnsDB tables.
3. Select the OnsDB tables required for the integration.
4. Save the configuration.
5. Continue the regular review and promotion process for the connector version.

The selected OnsDB tables are part of the connector specification, similar to selected Ons API models.

Retrieving OnsDB table data

Retrieving data from an OnsDB table works differently from retrieving data from Ons API models.

When retrieving an OnsDB table, the request must specify the OnsDB schema version that should be used. This is done with the `X-Stream-SchemaVersion` header.

For example:

http
GET /t/{onsdb-table-endpoint} HTTP/2
Host: api-development.ons.io
Accept: application/json
X-Stream-SchemaVersion: 4223

The schema version must refer to an available OnsDB data model. See the article Datamodellen in OnsDB for the currently supported OnsDB data models.

Schema versions

OnsDB table structures can change between schema versions. By explicitly specifying the schema version, the response is based on the table structure for that specific OnsDB data model.

Use a supported schema version and update the integration when the configured schema version is no longer supported.

For more information about supported OnsDB data models, see: Datamodellen in OnsDB.

Field filtering

Field filtering is not supported for OnsDB table responses.

This means that the fields in the response cannot be limited by selecting individual fields in the connector configuration or by using the following header:

X-Field-Whitelist

Because of this, OnsDB tables can return more data than strictly required for the integration. From a data minimization perspective, we recommend to use Ons API models whenever the required data is available through those models.