DataAPI

HandleData logo HandleData - Version 9.2.0

To manage DataAPIs as an API producer, you must have the following rights

  • Global permissions (on the user or group)

    • "DataAPIs": to view and modify HandleData DataAPIs

    • "DataAPIs - Creation": to create new DataAPIs

  • Right on the data source (DataBlock)

    • "Sharing"

  • Right on the DataAPI

    • "Modification"

To consume an API, you must

  • Be referenced as a user of the consumption module (future DataChain Marketplace)

DataAPIs are used to describe and configure data APIs based on datasets (DataBlocks) intended to be consumed outside DataChain Projects.

Summary

  • DataAPIs are used to share datasets from DataBlocks as APIs

  • Publication settings are used to describe and configure the API

    • Public metadata describe the API to consumers, and the endpoint can be used to customize the access URL

    • General column settings define the columns that can be exposed in the access settings, along with their characteristics

    • API accesses define the exposed columns and rows, as well as the consumers that can access them

      • Open access (maximum 1): all referenced users who have access to the DataChain Marketplace can view and consume the API

      • Limited access: only users and groups specified in the access can access the data.
        Warning, in the event of restrictive access synthesis for the DataAPI (configurable from the public metadata configuration area), Open access is ignored when the DataAPI is consumed by users with limited access membership.

      • row filter: limits access to data (rows)

  • Once the API is published, you can

    • update the data: the data is updated from the API’s published configuration (publication settings are not taken into account during this action)

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

    • update the published API configuration: publishes all or part of the publication settings (metadata, column settings, and accesses).
      If the column settings are updated, the accesses and data are automatically updated.

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

  • The update tracking table shows the update history for the published API

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

  • If you delete a DataAPI, the published API is automatically deleted at the same time

Overview

A DataAPI is a DataChain element made up of internal metadata, which identifies the element in the Project, and a set of Publication settings used to publish an API in order to share data from a data source internal to the Project (DataBlock).

Each API Publication 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 item in the dataset

  • Each column represents a variable in the dataset

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

API Publications are accessible by

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

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

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

Data source

The data source of an API must be a Project DataBlock. You must have the "Sharing" right on the source to create an API on the DataBlock data.
The source cannot be changed once it has been selected.

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

An impact check between the source column settings and the Publication settings is performed when the DataBlock is modified.
For example, you cannot delete a column from a DataBlock’s output settings if it is active in the Publication settings: you must first disable it in the DataAPI publication settings (and in the row filters if necessary).

Pay particular attention to the risk of inconsistencies between the source column settings and the published API column configuration.
Updating data from the published API configuration may fail if it is inconsistent with the data source settings.
To avoid this problem, modify the publication settings in parallel with the DataBlock settings, then update the published API configuration using the new settings.

DataAPI

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

DataAPI -DataAPI metadata
Label Description Required Editable

Label

Short description of the element

✅

✅

Description

Long description of the element

✅

Tags

Categorization of the element. Tags can be used to search for an element

✅

Publication settings

Publication settings define the configuration of the API that will be published.

When the API is published, the publication settings can be modified without affecting the configuration of the published API.
In this case, the settings visible in the publication settings represent the "draft" version of the API configuration.

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

Public metadata

The API Publication metadata is used to define the API access URL and describe the API to consumers.

DataAPI -API Publication metadata
Label Description Required Editable

Endpoint

Name of the endpoint from which the API access URL is created

✅

✅

Title

Short description of the published API

✅

✅

Details

Long description intended for API consumers

✅

Keywords

Categorization of the element. Keywords are a filter criterion for consumers

✅

Access synthesis

Additive or restrictive. Defines how columns are shared with users who have multiple accesses to the DataAPI

✅

✅

General column settings

The General column settings define the columns that can be exposed from the API access settings.
Different settings can be enabled on each exposed column.

DataAPI -General column settings
Label Description Required Editable Applicable column types

Type

Column type (from the source)

-

All

Label

Column label in the source

-

All

Alias

Unique, normalized, and public label 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 modify the alias, you must also modify the filter so that it works again.

✅

✅

All

Status (Active / Inactive)

Enable so that the column is available to be exposed in accesses

✅

✅

All

Description

Public description of the column, visible to consumers

✅

All

Id

Select to define the column as a unique identifier.
Consumers will be able to access a row by its identifier.
Only one column can be defined as the identifier

✅

All except List

Filterable

Select so that consumers can filter the data by one of the column values.
Clear this option to optimize performance.

✅

✅

All except List

IC

Select to make filter searches case-insensitive.
Affects both filters applied by API consumers and row filters defined in the access settings

✅

String only

Hide

Select 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 row filters for groups and users

✅

All except List

Hashable

Select to enable the "Hash" option for this column in the access settings.
The data will be visible in hashed form only to consumers affected by the filter where the option is selected.

✅

String and list of strings

API access

An access is used to configure the exposed columns, restrict access to rows, and define the consumers who can access the API.
Multiple 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.

When a DataAPI has multiple accesses, a synthesis of the columns accessible to each consumer through these accesses is performed. It can be additive or restrictive.

When it is additive, consumers have access to all columns in their limited accesses and to all columns in the DataAPI’s open access, if one exists.

When it is restrictive, consumers have access only to the common columns configured in their limited accesses. Open accesses are ignored for consumers who have limited accesses.

DataAPI -Access settings
Label Description

Access metadata

  • Label: 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 publishing the settings

Access type

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

  • Limited: only users and members of groups added to the access can access the API and the data defined in this access
    Warning: when access synthesis is restrictive (default value), open access is ignored when the DataAPI is consumed by users who are members of limited accesses.

Consumers

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

Columns

  • Active: enable the columns that will be visible to consumers of this access

  • Hash: the values will be visible but hashed

Rows

Use the row filter to restrict access to data rows.
Warning: you cannot filter on an inactive or hashed column.

Row filter

Access to exposed data can be restricted by adding one or more row filters.
The "IC" (case-insensitive) option that can be enabled in the column settings also affects the access row filter.

The filter cannot work if it is applied to a column that is inactive or hashed in the access settings, or if the Alias used is not the same as the Column alias.
If the filter contains an error, no data (rows) will be available to consumers concerned by the access.
DataAPI -Column types available for the row filter
Type Filterable

String

✅

Integer

✅

Big Integer

✅

Boolean

✅

Decimal

✅

List (all list types)
Simple syntax

Colonne Opérateur 'Valeur'

VILLE=='grenoble'

Result: consumers only see rows containing the value "grenoble" in the "VILLE" column

Syntax with cumulative filter

(Colonne Opérateur "Valeur" or Colonne Opérateur "Valeur") and (Colonne Opérateur "Valeur")

(VILLE=="grenoble" or CP=="38000") and (ANNE>="2020")

Result: consumers only see rows containing the value "grenoble" OR the value "38000" in the "CP" column AND all values greater than or equal to "2020" in the "ANNEE" column

Learn more about the filter syntax.

Example

A company manages its users through groups named after their region.

DataAPI -The dataset
year CA region

2022

892 235

Bretagne

2022

598 123

Auvergne-Rhône-Alpes

2022

125 789

Grand Est

2022

895 333

Corse

2023

592 683

Bretagne

2023

578 632

Auvergne-Rhône-Alpes

2023

859 265

Grand Est

2023

779 225

Corse

Brittany access

  • Access name: Bretagne

  • Limited access: 1 group

    • "Région Bretagne"

  • Active columns: year, CA

  • Row filter: region=="Bretagne"

Result

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

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

2022

892 235

2023

592 683

Brittany and Corsica 2022 and 2023 access

  • Access name: Bretagne et Corse 2022

  • Limited access: 2 groups

    • "Région Bretagne"

    • "Région Corse"

  • Active columns: Year, CA

  • Row filter: (region=="Bretagne" or region=="Corse") and (year=="2022")

Result

Members of the "Région Bretagne" group and those of the "Région Corse" group see the values in the Year and CA columns and rows 1 and 5.

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

2022

892 235

2022

895 333

Syntax rule

DataAPI -Filter syntax rule
Syntax Use case

()

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

Value operators

Operators use the same syntax for producer-side and consumer-side filters.

DataAPI -Convention / Operators
Operator Syntax Accepted types Example

Equal

==

String, Numeric, Boolean, Date

nom=='mon ami' ou nom==ami

Different

!=Actions available on an API Publication

String, Numeric, Boolean, Date

nom!='mon ami' ou nom!=ami

Greater than

> ou =gt=

Numeric, Date

> 10 ou =gt=10

Greater than or equal to

> = ou =ge=

Numeric, Date

> = 10 ou =ge=10

Less than

< ou =lt=

Numeric, Date

< 10 ou =lt=10

Less than or equal to

< = ou =le=

Numeric, Date

< = 10 ou =le=10

In list

=in=

String, Numeric, Boolean, Date

=in=(ami,copain)

Not in list

=out= ou =notIn=

String, Numeric, Boolean, Date

=out=(ami,copain) ou =notIn=('mon ami','mon copain')

Between

=between=

Numeric, Date

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

Not between

=notBetween=

Numeric, Date

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

Contains

=contains=

string

=contains=(A)

Does not contain

=notContains=

string

=notContains=(B)

Begins with

=beginsWith=

string

=beginsWith=A ou =beginsWith='A B'

Does not begin with

=notBeginsWith=

string

=NotBeginsWith=A ou =NotBeginsWith='A B'

Ends with

=endsWith=

string

=endsWith=A ou =endsWith='A B'

Does not end with

=notEndsWith=

string

=notEndsWith=A ou =notEndsWith='A B'

Is null / Is not Null

=isNull=

String, Numeric, Boolean, Date

Nom=isNull=true ou Nom=isNull=false

Restricting access based on groups or users defined in a source column

Access to rows can be restricted based on the values they contain.

To restrict access based on a group or user defined in a source column, you must use the specific operators described below.

User and group operators

Variables can be added to filters to restrict access to exposed data to specific users or user groups.

3 variables are available

  • @DcUserGroups

  • @DcUserMail

  • @DcUserLogin

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

You can hide this column by selecting the "Hide" option in the general column settings.

Expected syntax

nomDeLaColonne=operateur=variable
DataAPI -User and group operators
Variable / Operator =contains= =notContains= =containsAllOf= =containsOneOf= =containsNoneOf=

@DcUserLogin

The value contains the user’s login

The value does not contain the user’s login

N/A

N/A

N/A

@DcUserMail

The value contains the user’s email address

The value does not contain the user’s email address

N/A

N/A

N/A

@DcUserGroups

N/A

N/A

The value contains all groups the user belongs to

The value contains one of the groups the user belongs to

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

  • Jean belongs to the Admin group

  • Alice belongs to the Administrateur and Utilisateur groups

  • Cynthia belongs to the Utilisateurs group

DataAPI -Datablock columns and values
id data auth_group

1

Donnée1

Admin

2

Donnée2

Utilisateur Administrateur

3

Donnée3

Admin Utilisateur

4

Donnée4

Admin Administrateur Utilisateur
DataAPI -Variable
auth_group=containsAllOf=@DcUserGroups

The filter allows the user to see only the data rows where the value of the Auth_group column contains all values matching the groups to which the user belongs.

  • Jean sees all rows because the value "Admin" is included in the value "Administrateur"

  • Alice sees rows 2 and 4

  • Cynthia sees no rows because "Utilisateurs" is not a value included in "Utilisateur"

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

DataAPI -Example of a secured variable
nomDeLaColonne=operateur=#@DcUserGroups#
DataAPI -Secured Datablock columns and values
id data auth_group

1

Donnée1

#Admin#

2

Donnée2

#Utilisateur#Administrateur#

3

Donnée3

#Admin#Utilisateur#

4

Donnée4

#Admin#Administrateur#Utilisateur#

Project versions and DataAPI URLs

A DataAPI is attached to a Project version. DataAPIs from several versions of the same Project can be published and consumed simultaneously.

The Project’s root code is included in their URL. It is shared by all versions.

By default, a DataAPI URL allows the data from its instance in the active version of its Project to be consumed.

To consume the DataAPI from another version of a Project, it must be specified using the dcProjectVersion parameter in the URL.
Example: http://[host]/dmp-api/data/[project_root_code]/[access_point]/count?dcProjectVersion=2

A consumer using the address without this parameter always consumes the active version of the Project. Before changing this version, check that the consumed DataAPIs are published and that their data and parameters are suitable for consumers.

Activating a version does not automatically publish its DataAPIs. Their publication statuses and access rights remain applicable.

For a smooth activation, check the DataAPIs to be published in the version to activate and their access points to ensure service continuity for the current consumers of the active version.

Changing the root code in the advanced settings applies to all versions of the Project. It is separate from changing the active version.

To manage versions, see Project Versioning.

Create a DataAPI

From HandleData, click the Sharing  DataAPI menu to access the DataAPI list, then click the New icon.

Creation is divided into 4 steps.

DataAPI -Creating a DataAPI
Step Description

DataBlock

Select the DataAPI source dataset.
Only DataBlocks on which you have the "Sharing" right are visible in the list.
The source cannot be changed once the DataAPI has been created.

Metadata

  • DataAPI: define the metadata visible only to members of the DataChain Core Project

  • API Publication: define the metadata visible to API consumers

Columns

Enable the columns to publish and configure the general column settings

Access

Configure an initial API access.
It can be "Open" (all users who have access to the consumption module) or concern only specific users.
Access to data can be restricted using a row filter.

Once the DataAPI has been created, the API can be published from the list or from the DataAPI page using the Publish button.

Manage an API Publication

All users who have the "Sharing" right on the source DataBlock can modify and perform actions on the API Publication.

For the API to be visible to consumers and for the 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 bulk action is launched from the DataAPI 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, the action will fail and the API will remain unpublished.

API Publication status

  • Unpublished: the API has never been published; consumers see neither the API metadata nor the data

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

  • Unavailable: the API is published but has been disabled, meaning that the data (columns and rows) can no longer be consumed; only the metadata remains viewable (access URL, title, description, and keywords)

Action Detail Available Unavailable Unpublished

Publish

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

✅

Update data

Updates the API data (rows) from the published API configuration.
If you modified the publication settings, use the Update configuration action to update the data using the new settings.
This action can be automated from DC-Maestro.

✅

✅

Clear data

Deletes all API data (rows).
The API still returns metadata (Publication and column).
Use the Update data or Update configuration actions to update the data.

✅

✅

Disable

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

Enable

Makes the API Publication Available: the Publication metadata and data (columns and rows) can be consumed.

✅

Update configuration

Updates all or part of the API configuration (metadata, column settings, accesses).
If the column settings are updated, the accesses must also be updated, and the API data (rows) will be refreshed using these new settings.

✅

✅

Publish the API

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

An API can be published from the DataAPI page or from the list: either on the item or as a bulk action.

Inactive accesses are not published and therefore have no effect for consumers.

Update data

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

Data can be updated from the DataAPI page or from the list: either on the item or as a bulk action.

If the source has been modified, the source column schema and publication settings may conflict, preventing the update from being completed.
In this case, the API and the data it contains are not updated: it remains in its last stable published state.

Modify the publication settings 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), remains visible to consumers.

Update the configuration

Once the API is published, its configuration can be updated.

The settings of a Publication can be modified independently: until you update the configuration of the published API, the published API is not affected by changes you make to the Publication settings.

Modify Publication settings

Some changes trigger automatic changes or require you to make changes to the accesses.

DataAPI -Changes to general column settings
Label Update in the access

Status

* A confirmation dialog allows you to choose whether enabled columns should be added as active or inactive in existing accesses. * Disabled columns are automatically disabled in all accesses: if column filters were configured on these columns, they no longer work.

Alias

If column filters were configured on these columns, they no longer work.

Id

No impact on accesses

Filterable

No impact on accesses

IC

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

Hide

No impact on accesses

Hashable

* Option enabled: the hash option will be available but must be selected manually * Option disabled: hashed options will be disabled automatically

Update the configuration

Once you have made the necessary changes to all or part of the publication settings (metadata, general column settings, API accesses), click Update configuration.

Warning: if you have disabled columns or modified their Alias in the general column settings, 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 based on the settings you selected

  • Metadata: affects only the API’s public metadata; does not update the data

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

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

Change the API publication status

The "Enable" and "Disable" actions change 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 disabled, meaning that the data (columns and rows) can no longer be consumed; only the metadata remains viewable (access URL, title, description, and keywords)

The status can be changed from the DataAPI page or from the list: either on the item or as a bulk action.

Track updates

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

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

For example, if you perform a data update and the action fails because another action is already in progress, the data remains available in the last stable version of the API that was updated.

Delete a DataAPI

Deleting a DataAPI associated with a published API immediately deletes the API publication.
All exposed data is deleted, but a new DataAPI can still be created from the source DataBlock.

API consumption

If the API contains an 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 users and groups present in the Limited accesses can access the Publication and its data.

If the API contains both an Open access and Limited accesses and the access synthesis is restrictive (default value), the Open access settings are not applied to consumers of the Limited accesses.

The columns and rows a user sees depend on the DataAPI access settings.

Case of a user defined in multiple accesses

The data available to a user is affected if the user is present in the settings of multiple accesses (as a user or through their group).

When the DataAPI access synthesis is additive:

  • Accessible columns: all columns present in the limited accesses of which the user is a member and in the open access, if one exists, are available

  • Row filter: all rules defined in the filters are cumulative

When the DataAPI access synthesis is restrictive:

  • Accessible columns: only columns common to the limited accesses are available. Columns provided by the open access are ignored

  • Row filter: all rules defined in the filters are cumulative

Example

DataAPI -The dataset
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

Settings of the accesses in which the user is added as a consumer (through their groups, for example)

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

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

    Result

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

Column B

Value 1A

Value 2A

Value 3A

Value 3A

Access conditions for a DataBlock API

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

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

APIs can be consumed directly using the API access URL provided to you by the API producer.

Query syntaxes and operators

DataAPI -Example of a query to the DataAPI
https://monInstance/dmp-api/data/[code_racine]/[point_acces]?select=id,nom&filter=nom=beginsWith=A
DataAPI -Query syntaxes (consumption only)
Syntax Description Required?

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

Base access URL

YES

exposition?

Name of the endpoint assigned when configuring the API at DataBlock level

YES

select=

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

filter=

Filters based on the defined filter settings
Example: filter=nom=beginsWith=A
Learn more about the filter syntax.

page=

Indicates the returned page. By default, this is page 1
Example: page=5

hitsPerPage=

Indicates the number of rows per page
Example: hitsPerPage=50

useCache=

Indicates whether the cache (persistence) is used
Example: useCache=true

sort=

Sort based on the defined settings
Example: sort=nom:desc

format=

Indicates the data output format (xml/json)
Example: format=xml

rootTag=

Specifies the label of the root tag for XML data returned by the query
Example: rootTag=racine

rowTag=

Specifies the label of each record tag returned by the query
Example: rowTag=ligne

ctx:

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

&

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

Data display format

For more information about the default values of the settings defining the display format of data returned by a query, see the Marketplace documentation.

Dernière mise à jour le 28 octobre 2026 à 18:35