API exposure

Logo HandleData HandleData - Version 8.6.0

To manage API Exposures as an API Producer, you must have the following access

  • Global permission (on the user or group)

    • exposition": to view and modify HandleData API Expositions

    • exhibition-create": to create new exhibitions

  • Data source rights (DataBlock)

    • Modification

To use an API you must

  • Be registered as a user of the consumption module (future Market Place DataChain)

API Expositions are used to describe and configure data APIs from datasets (DataBlock) intended to be consumed outside DataChain Projects.

To migrate existing APIs (visible in the list of DataBlocks from GenericsData) to the new version linked to the HandleData shared elements described on this page, refer to Expositions migration guide.

In summary

  • The Expositions API allow datasets from DataBlock to be shared in the form of APIs

  • The publication-parameters allow the API to be described and parameterised

    • The Public metadata describe the API to consumers and the access point allows the access URL to be customised

    • The general column settings define the columns that can be exposed in the access settings, as well as their characteristics

    • The API access are used to define the exposed columns and rows and the consumers that can access them.

      • 'Open' access (maximum 1): all referenced users who have access to the data consumption module can view and consume the API

      • 'Restricted' access: only the users and groups specified in the access can access the data. Important Open access settings do not apply to limited access users.

      • It is possible to restrict access to data (line) by adding a filter on line

  • When API is published, you can

    • update data : data is updated from the published configuration of the API

    • delete data: all data (rows only) is deleted from the published API.
      Column metadata (type, alias and description) remain visible

    • modify the publication parameters to update the configuration of the published API.
      Metadata, column parameters and access can be updated.
      If column parameters are updated, accesses and data are automatically updated.

    • change publication status of the API: if you disable the API, it becomes Unavailable. Consumer users can no longer view the API documentation, nor consume the dataset. The API must then be enabled to be Available to consumers again.

  • The Track updates table shows the history of updates to the published API.

    • If an update fails, the Publication remains in its latest stable version (for example, if you make a data update and that action fails because another action is already in progress, the data will remain available in the latest stable version that was updated to the API)

  • If you delete an Exposition, the published API is automatically deleted at the same time

General

An API-Exposition is a DataChain element made up of internal metadata, which identifies the element in the Project, and a set of Publication parameters which allow an API to be published in order to share data from a data source internal to the Project (DataBlock).

Each Publication API consists of a set of public metadata and a ‘flat’ (tabular) dataset, made up of columns (typed, from 1 to n) and rows (from 0 to n).

  • Each row represents an element in the dataset

  • Each column represents a variable in the dataset

The data and metadata of an API Publication can be consulted by all consumers who have access to the API by querying the published API.

API Publications can be accessed by

  • consumer users, referenced and authenticated in the DataChain Platform, who access shared datasets outside Projects

  • third-party applications (Power-BI, etc)

The data available (columns and rows) and the functionalities (id, filterable, etc.) visible and available to consumers depend on the publication parameters.

Data source

The data source for an API must be a DataBlock in the Project. You must have the ‘Share’ right on the source to create an API on the DataBlock’s data.
It is not possible to modify the source once it has been selected.

Columns of type words, binary, files and geometry cannot be published by API.

An impact check between the source column parameters and the Publication parameters is carried out in the event of modifications to the DataBlock +. For example, it is impossible to delete a column in the output parameters of a DataBlock if it is active in the Publication parameters: you must first deactivate it in the Exhibition-side publication parameters (and in the row filters if necessary).

Particular attention should be paid to the risk of inconsistency between the source column settings and the published API column configuration.
Updating data from the published API configuration may fail if there is an inconsistency with those of the data source.
To avoid this problem, modify the publication parameters in parallel with those of the DataBlock, then update the published API configuration using the new parameters.

API Exhibition

The API Exhibition is an internal element of the Project that allows you to configure and share API Publications.
The Exhibition metadata identifies and describes the element in the Project and is visible only to users who are members of the Project.

API exposure -Exhibition metadata
Title Description Mandatory Modifiable

Description

Short description of the element

✅

✅

Description

Long description of the element

✅

Tags

Categorising the item. Tags are used to search for an element

✅

Publication parameters

The publication parameters are used to define the configuration of the API that will be published.

When the API is published, the publication parameters can be modified without affecting the configuration of the published API. In this case, the parameters visible in the publication parameters represent the ‘draft’ version of the API configuration.// An icon visible in the zone dedicated to the published API indicates the differentiating elements

To update the configuration of a published API from the publication parameters, use the Update configuration button located in the API Publication zone.

Public metadata

API Publication metadata* is used to define the URL for accessing the API and to describe the API to consumers.

API exposure -API Publication metadata
Title Description Mandatory Modifiable

Access point

Name of the access point from which the API access URL is created.

✅

✅

Title

Short description of the published API

✅

✅

Details

Long API Consumer Description

✅

Keywords

Categorisation of the element. Keywords are a filter feature for consumers.

✅

General column settings

The General column settings define which columns can be exposed from the API access settings.
Different parameters can be activated for each exposed column.

API exposure -General column parameters
Heading Description Mandatory Modifiable Type of columns concerned

Type

Column Type (from source)

-

All

Name

Column label in source

-

All

Alias

The unique, normalised and public name of the column, visible to consumers.
The alias must be used to write filters.
If an access has a row filter linked to a column and you change the alias, you must also change the filter so that it works again.

✅

✅

All

Status (Active / Inactive)

Enable to make the column available for exposure in accesses.

✅

✅

All

Description

Public description of column, visible to consumers

✅

All

Id

Tick so that the column is defined as a unique identifier.
Consumers will be able to access a row by its identifier.
Only one column can be defined as a unique identifier.

✅

All except List

Filterable

Check so that consumers can filter the data according to one of the values in the column. + Check so that consumers can filter the data according to one of the values in the column. Uncheck to optimise performance.

✅

✅

All except List

IC

Check to make the filter search case insensitive.
Impacts both the filters performed on the consumer side of the API and the line filters defined in the access parameters.

✅

String only

Hide

Check to make the column and rows inaccessible to all consumers while retaining the ability to use it in row filters. This option is particularly suitable for line filters for groups and users.

✅

All except List

Hachable

Check to enable the ‘Hash’ option for this column in the access parameters. The data will only be visible minced for consumers affected by the filter where the option is ticked.

✅

Crater string and string list

API access

Access allows you to set the exposed columns, restrict access to rows and define consumers who will be able to access the API.
Several accesses can be configured for the same API.
Only users with access to the consumption module are visible in the list and can consume the API.

API exposure -Access parameters
Title Description

Access metadata

  • Title: short description of the access

  • Description: long description of the access

  • Status: if the access is inactive, it will not be taken into account when the parameters are published.

Access type

  • Open: all referenced users who have access to the consumption module can access the API and the data defined in this access.

  • Restricted: only users and members of groups added to the access can access the API and the data defined in this access. Note that the parameters of the ‘Open’ access do not apply to users and groups of the ‘Limited’ access.

Consumers

If the access is Limited, at least one group or user must be selected.

Columns

Active: activate the columns that will be visible to the users of this access. * Hash: values will be visible but hashed

Rows

Use the Line filter to restrict access to rows of data.
Note that it is not possible to filter on an inactive or hashed column.

Line filter

Access to exposed data can be restricted by adding one or more line filters.
The ‘IC’ (case insensitive) option, which can be activated in the column parameters, also has an impact on the line filtering of accesses.

The filter will not work if it is positioned on a column that is inactive or hashed in the access parameter, or if the Alias used is not the same as that of the Column.
If the filter contains an error, no data (row) will be available for the consumers affected by the access.
API exposure -Type of columns available for the row filter
Type Filtrable

String

✅

Integer

✅

Big Integer

✅

Boolean

✅

Decimal

✅

List (all list types)
simple syntax

Column Operator ‘Value’

CITY=='grenoble

Result

consumers only see rows containing the value ‘grenoble’ in the ‘CITY’ column.

Syntax with cumulative filter (Column Operator ‘Value’ or Column Operator ‘Value’) and (Column Operator ‘Value’)

(CITY==‘grenoble’ or CP==‘38000’) and (YEAR>=‘2020’)

Result: consumers only see rows that contain the value ‘grenoble’ OR that contain the value ‘38000’ in the ‘CP’ column AND all values greater than or equal to ‘2020’ in the ‘YEAR’ column

Find out more about the Syntax rule.

Example

A company manages its users by groups named by their region.

API exposure -The data set
year CA region

2022

892 235

Brittany

2022

598 123

Auvergne-Rhône-Alpes

2022

125 789

Grand Est

2022

895 333

Corsica

2023

592 683

Brittany

2023

578 632

Auvergne-Rhône-Alpes

2023

859 265

Grand Est

2023

779 225

Corsica

Bretagne access

  • Access name: Bretagne

  • Limited access : 1 group

    • Brittany Region

  • Active columns: year, CA

  • Filter on rows: region=="Bretagne

Result

Members of the ‘Région Bretagne’ group only see the values in columns A and B and rows 1 and 4.

API exposure -Result for users who are members of the Bretagne group
Year CA

2022

892 235

2023

592 683

Access Brittany and Corsica 2022 and 2023

  • Access name: Bretagne et Corse 2022

  • Limited access: 2 groups

    • Brittany Region

    • Corsica Region

  • Active columns: Year, CA

  • Filter on lines: (region==‘Bretagne’ or region==‘Corse’) and (year==‘2022’)

Result

Members of the ‘Brittany Region’ group and those of the ‘Corsica Region’ group see the values in columns Year and CA and rows 1 and 5.

API exposure -Result for users who are members of the Bretagne group
Year CA

2022

892 235

2022

895 333

Syntax rule

API exposure -Syntax rule for filters
Syntax Use cases

()

use to group 2 non-cumulative conditions (or)

or

use to add an optional condition

and

use to add a mandatory condition

“” or ''

use single or double quotes to enclose values

Operators on values

Operators have the same syntax for producer and consumer filters.

API exposure -Convention / Operators
Operator Syntax Accepted types Example

Equal

==

String, Numeric, Boolean, Date

name=='my friend' or name==friend

Different

!=Actions available on an API Publication

String, Numeric, Boolean, Date

name!='my friend' or name!=ami

Superior

> or =gt=

Numeric, Date

> 10 or =gt=10

Greater than or equal to

> = or =ge=

Numeric, Date

> = 10 or =ge=10

Lower

< or =lt=

Numeric, Date

< 10 or =lt=10

Lower or equal

< = or =le=

Numeric, Date

< = 10 or =le=10

In list

=in=

String, Numeric, Boolean, Date

=in=(friend,boyfriend)

Not in list

=out= or =notIn=

String, Numeric, Boolean, Date

=out=(friend,boyfriend) or =notIn=('my friend','my boyfriend')

Between

=between=

Numeric, Date

=between=(2,5) or =between=('','')

Not between

=notBetween=

Numeric, Date

=notBetween=(2,5) or =notBetween=('','')

Contains

=contains=

string

=contains=(A)

Does not contain

=notContains=

string

=notContains=(B)

Starts with

=beginsWith=

string

=beginsWith=A or =beginsWith='A B'

Does not begin with

=notBeginsWith=

string

=NotBeginsWith=A or =NotBeginsWith='A B'

Ends with

=endsWith=

string

_=endsWith=A or =endsWith

Does not end with

=notEndsWith=

string

=notEndsWith=A or =notEndsWith='A B'

Is null / Is not null

=isNull=

String, Numeric, Boolean, Date

Name=isNull=true or Name=isNull=false

Restrict access according to groups or users defined in a source column

You can restrict access to rows according to the values they contain.

To limit access according to a group or user defined in a source column, you need to use the specific operators described below.

Operators on users and groups

Variables can be added to filters to restrict access to exposed data to certain users or groups of users.

3 variables are available

  • @DcUserGroups

  • @DcUserMail

  • @DcUserLogin

For the filter to apply, the Datablock must have a column containing, for each line, the list of user(s) and group(s) concerned by the filter.

This column can be hidden by checking the “Hide” option in the general column parameters.

Expected syntax

columnName=operator=variable
API exposure -Operators on users and groups
Variable / Operator =contains= =notContains= =containsAllOf= =containsOneOf= =containsNoneOf=

@DcUserLogin

Value contains user login

Value does not contain user login

N/A

N/A

N/A

@DcUserMail

Value contains user’s mail

Value does not contain user mail

N/A

N/A

N/A

@DcUserGroups

N/A

N/A

Value contains all groups to which the user belongs

Value contains one of the groups to which the user belongs

The value contains none of the groups to which the user belongs
The operator behaves like a %like% in Database.
For example, if a user belongs to the Admin group and the authentication column contains the value Administrator, since the Admin value is contained in the Administrator value, the user will be able to access the data.
The example below details this behavior and how to avoid it.
Example of use

  • John is a member of the Admin group

  • Alice belongs to the Administrator and User groups

  • Cynthia is a member of the User group.

API exposure -Datablock columns and values
id data auth_group

1

data1

Admin

2

Data2

User Administrator

3

Data3

User Admin

4

Data4

Admin User Administrator

Variable

auth_group=containsAllOf=@DcUserGroups

The filter allows the user to see only those data rows whose Auth_group column value contains all values equal to the values of the groups to which he belongs.

  • John sees all rows, because the value “Admin” is included in the value “Administrator”.

  • Alice sees lines 2 and 4

  • Cynthia sees no lines, because “Users” is not a value included in “User”.

To avoid including unwanted values, it’s best to add a special character (e.g. #) to enclose each group or user value in the column, and to add the same character around the variable.

Example of a secure variable

columnname=operator=#@DcUserGroups#
API exposure -Secure Datablock columns and values
id data auth_group

1

data1

#Admin#

2

Data2 #User#Administrator#

3

Data3 #Admin#User#

4

Data4 #Admin#Administrator#User#

Create an API Exhibition

From HandleData, click on the Shares  Exhibitions to access the list of Exhibitions, then click on the New icon.

Creation is divided into 4 steps.

API exposure -Creating an Exhibition
Step Description

DataBlock

Select the source dataset of the API Exhibition.
Only DataBlocks on which you have the “Share” right are visible in the list.
It is not possible to modify the source once the Exhibition has been created.

Metadata

Exposition : define the metadata visible only to members of the DataChain Core Project. API Publication: define metadata visible to API consumers.

Columns

Activate columns to be published and configure general column parameters.

Access

Set an initial API access. It can be “Open” (all users who have access to the consumption module) or concern only certain users.
It is possible to limit data access with a filter on lines.

As soon as the Exhibition is created, the API can be published from the list, or from the Exhibition page, from the Publish button.

Managing an API Publication

All users with “Share” rights on the source DataBLock can modify and perform actions on the API Publication.

In order for the API to be visible to consumers and for data to be consumed, the API must have been published.

If an action fails, the API data remains available in its last stable state.

The actions available on an API Publication depend on its status.

If a grouped action is launched from the Exhibitions table, it is possible to launch actions that are inconsistent with the status +. For example, if you launch a data update on an unpublished API, this action will fail and the API will remain unpublished.

API publication status

  • Unpublished: the API has never been published, so consumers don’t see API metadata or data.

  • Available: API is published and data can be consumed

  • Unavailable: the API is published but has been deactivated, i.e. the data (columns and rows) can no longer be consumed; only the metadata can still be consulted (access URL, title, description and keywords).

Action Detail Available Unavailable Unpublished

Publish

Publishes the API for the first time. If the task is successful, the API is Available.

✅

Update data

Updates API data (lines) from published API configuration. If you’ve changed the publication settings, use the Update configuration action to update the data from the new settings.
This action can be automated from within DC-Maestro.

✅

✅

Empty data

Delete all data (lines) from the PLC.
API always returns metadata (Publication and column).
Use actions Update data or Update configuration to update data.

✅

✅

Deactivate

Makes API Publication Unavailable: only Publication metadata is still consumable.
Use the Enable action to make data (columns and rows) available again.

Activate

Makes API Publication `Available': Publication metadata and data (columns and rows) are consumable.

✅

Update configuration

Updates all or part of the API configuration (metadata, column parameters, access).
If the column parameters are updated, the accesses must also be updated, and the API data (rows) will be updated with the new parameters.

✅

✅

Publish API

At least one access must be active in order to publish the API.
The action may take a few minutes.
If the action is successful, the API is published and available to consumers.

It is possible to publish an API from the Exhibition page or from the list: either on the item, or as a grouped action.

Inactive accesses are not published, so they have no effect on consumers.

Update data

This action updates all API data from the published API configuration.
This action can be automated from within DC-Maestro.

Data can be updated from the Exhibition page or from the list: either on the item, or as a grouped action.

If changes have been made to the source, it is possible that the source’s column layout and publication parameters may conflict, and that the update cannot be performed. + In this case, the API and the publication parameters will be updated. In this case, the API and the data it contains will not be updated: it remains in its last published stable state.

Modify the publishing parameters to correct the problem, then update the API column configuration. The action will update the data at the same time.

Delete data

This action deletes all API data.

Metadata, including column metadata (alias, type and description) are still visible to consumers.

Update configuration

Once the API has been published, it is possible to update the API configuration.

Publication parameters can be modified independently: as long as you have not updated the published API configuration, the published API is not affected by any changes you make to the Publication parameters.

Change Publication settings

Some modifications lead to automatic changes or require you to make changes to accesses.

Modification of general column parameters

Header Update in access

Status

A confirmation modal allows you to choose whether activated columns should be added as active or inactive in existing accesses. * Deactivated columns are automatically deactivated in all accesses: if column filters were positioned on these columns, they are no longer functional.

Alias

If column filters were set on these columns, they are no longer functional.

Id

No impact on access

Filtrable

No impact on access

IC

Column filters will become case-sensitive or case-insensitive depending on whether the option is enabled or disabled.

Hide

No impact on access

Hachable

Option enabled: the 'chop' option will be available, but must be checked manually. * Option disabled: chopped options will be disabled automatically

Update configuration

When you have made the necessary changes to all or part of the publishing parameters (metadata, general column settings, API access), click on Update configuration.

Caution: if you have deactivated columns or modified their Alias in the general column parameters, remember to check that the row filters defined in the accesses have been updated with the new Alias +. Otherwise, the filter will not work.

The API is updated according to the parameters you have selected

  • Metadata: impacts only the API’s public metadata, does not update data

  • Columns: updates data. Accesses must be updated at the same time as columns.

  • Accesses: do not update data. It is possible to update accesses only.

Modify API publication status

The “Enable” and “Disable” actions modify the API Publication status and data access.

  • Available": the API is published. Metadata and data can be consumed.

  • Unavailable": the API is published but has been deactivated, i.e. the data (columns and rows) can no longer be consumed; only the metadata (access URL, title, description and keywords) can still be consulted.

It is possible to modify the status from the Exhibition page or from the list: either on the item itself, or as a grouped action.

Track updates

The update tracking table shows the latest actions performed on the API.

If an update fails, the Publication remains in its latest stable version.

For example, if you make a data update and this action fails because another action is already in progress, the data will remain available in the last stable version that was updated to the API.

Delete an API Exposure

Deleting an Exposure associated with a published API immediately deletes the API publication.
All exposed data is deleted, but it is still possible to create a new Exposure from the source DataBlock.

API consumption

If the API contains Open access, all users who have access to the consumption module can view the API Publication and consume the data. + If the API contains only one or more Limited accesses, only the users and groups present in the Limited accesses can access the Publication and its data. If the API contains only one or more Limited accesses, only users and groups present in the Limited accesses can access the Publication and its data.

If the API contains both Open and Limited accesses, the Open access settings are not applied to Limited access consumers.

The columns and rows a user sees depend on the parameters of the access he is in.

Case of a user defined in several accesses

The data available to a user is impacted if he is present in the parameters of several accesses (as a user or via his group).

  • Accessible columns: only values and columns common to both accesses are available (restrictive synthesis).

  • Filter on rows: all rules defined in filters are added together (additive synthesis).

Example

The data set

Column A Column B Column C

Value 1A

Value 1B

Value 1C

Value 2A

Value 2B

Value 2C

Value 3A

Value 3B

Value 3C

Value 3A

Value 3B

Value 3C

Parameters for accesses in which the user is added as a consumer (via his groups, for example)

  • Access 1: Columns A and B active + row values containing 1

  • Access 2: Columns B and C active + line values containing 3

    Result

    The consumer only sees values in column B and rows 1 and 3

Column B

Value 1A

Value 2A

Value 3A

Value 3A

DataBlock API access requirements

To consume a shared element outside DataChain Core, a DataBlock API, you must have access to the consumption module.

As a consumer, you can access the APIs * to which you have been added as a consumer (you or a group to which you belong) * which are accessible to all users of the consumption module.

APIs can be consumed directly from the API access URL provided by the API producer.

Query syntaxes and operators

Example of a request to the exhibition API

https://monInstance/dcv-api/version/data/exposition?select=id,nom&filter=nom=beginsWith=A
API exposure -Query syntaxes (consumption only)
Syntax Description Mandatory ?

http://…​../service/data/

basic access URL

OUI

exposure?

Name of access point assigned during DataBlock API configuration

YES

select=

Selects the columns to be returned in the response.
If this section is not specified, all exposed columns are returned.

filter=

Filters according to defined filter parameters. Example: filter=name=begins _filter=name=beginsWith=A
Learn more about Syntax rule.

page=

Indicates the page returned. The default is page 1 +. Example: page=5

hitsPerPage=

Indicates the number of lines per page + Example Example: hitsPerPage=50

useCache=

Indicates whether the cache (persistence) is used or not +. Example: useCache=true

sort=

Sort according to defined parameters
Example: sort=name:desc

ctx:

Indicates the context of the instance used
Example : ctx:0

&

Character to add between each filter
Example: sort=ipp:asc _sort=ipp:asc,nom:desc&hitsPerPage=50