Exposure DataBlock (API)
Introduction
Each DataBlock can be consumed via a Rest API (GET method).
The consumption of DataBlocks datasets via the API must be configured at the level of the exposed DataBlock.
|
The rights apply differently depending on whether the DataBlock is persisted or not. In "Live" mode (non-persisted), the user must have rights to the entire value chain of the elements linked to the element (Connector(s), Repository(s), Business Entity(ies) and DataBlock(s)). In Persisted Mode, only DataBlock output rights are taken into account. |
Exposing DataBlock data
It is possible to expose the data of a DataBlock from
-
the list of DataBlocks: click on the icon
-
the DataBlock page: click on the action menu and then on "DataAPI Exposure".
Configuring API exposure
By default, DataBlocks are not exposed.
Various parameters must be set to expose the data in a DataBlock.
image:ecran_configuration.png [API Configuration Screen, API Configuration Screen]
Access point variable (Mandatory)
Corresponds to the part in bold in the example below
…//…./service/data/exposure?select=DateName,Sex,LastName,DateName,DPT&filter=Sex=in=(4,3)&hitsPerPage=1000
Button to click to expose Datablock data and create access links
Data description (visible to end users consuming the API)
Column search zone
DataBlock column labels
Column label to be used by end users in the URL syntax.
Corresponds to the parts in bold in the example below +.
…//…./service/data/exhibition?select=id,surname,firstname&filter=id=in=(4,3)&hitsPerPage=1000
Column description (visible to end users consuming the API)
Indicates whether the column is exposed or not. An unexposed column is not consumable by the API.
Indicates whether the column is hidden in the show (for example the column linked to filters on groups and users)
Indicates whether a column should be used as a primary key (pay attention to data uniqueness).
Used to access a row by its identifier
Select to ignore case and accents when searching.
Displays exhibition history
Displays available filters for exposure and allows new filters to be created
Access point configuration and API modification
As soon as the API is exposed, 3 different access points are available +. Exposure can be disabled and updated.
Returns the number of lines. This url can be completed with filter parameters.
…//…./service/data/MonEp/count?filter=Sex=in=(4,3)
Returns the data (depending on the filters and the query performed, refer to paragraph Syntaxes and operators).
Displays the Rest DataBlock API information screen.
The documentation is dynamic and specific to each Datablock, i.e. aligned with the configuration performed.
Enables/Disables the API.
Inactive exposures are no longer operational for this DataBlock.
Click to update the exposure data (data, filters, etc.).
Click to delete all exposed data
Exposure tracking
The exposure tracking tab tracks all the exposures you have made. Each time changes are made, the previous exposure is deleted.
]
Permissions by filter
Access to exposure data can be restricted by adding filters from the "Permissions by filter" tab.
You must first set up a filter and then associate it with one or more users or groups.
image:api-filter.svg [Filter form]
The filter is only applied to the user(s) or members of the group(s) associated with the filter.
Click on the 
icon in the list of filters to associate users.
Add the user(s) and group(s) to be associated, then click on "Save".
Consuming exposed data
Conditions for accessing a DataBlock API
To consume a DataBlock API, the user must have
-
an account in the DataChain instance concerned
-
an access token.
The access token can be obtained
from the account management page * via the authentication service * via the authentication service, Authentication API
Access to Rest API documentation
To access the documentation page, use the URL of the "Documentation" access point.
Paste the access token (learn more about access tokens)
Click to display the documentation.
The documentation is displayed below the form
[description of the exposed element].
Description of exposed dataset (if populated)
List of available columns (label, type and description if populated)
URL for accessing the data.
Use this zone to perform tests and display the result in the page (refer to Syntaxes and operators)
Array containing the result of the query
From PowerBI
It is possible to consume the exposed data of a DataBlock from PowerBI’s DataChain connector.
To follow the creation steps, go to the tutorial Consuming an exposed DC API from PowerBi.
Syntaxes and operators
API request syntaxes
The access token is mandatory.
It must be placed in the request header (Bearer token).
Example of a request to the exhibition API
https://monInstance/service/data/exposition?select=id,nom&filter=nom=beginsWith=A
Request syntax (consumption only)
| Syntax | Description | Mandatory ? |
|---|---|---|
basic access URL |
|
|
exposure? |
Name of access point assigned when configuring the API in the DataBlock |
|
select= |
Selects the columns to be returned in the response. |
|
filter= |
Filters according to the defined filter parameters. Example: filter=name=begins _filter=name=beginsWith=A |
|
page= |
Indicates the page returned. The default is page 1 +. Example: page=5 |
|
hitsPerPage= |
Indicates the number of lines per page + Example Example: page _hitsPerPage=50 |
|
useCache= |
Indicates whether the cache (persistence) is used or not + Example : hitsPerPage=50 Example: _useCache=true |
|
sort= |
Sort according to defined parameters |
sort sort=name:desc |
ctx: |
Indicates the context of the instance used |
|
ctx: |
ctx:0 |
|
& |
Character to be added between each + filter Example: sort=ipp:asc,name:desc _sort=ipp:asc,name:desc&hitsPerPage=50 |
Operators on values
| Operator | Syntax | Accepted types | Example |
|---|---|---|---|
Equal |
== |
String, Numeric, Boolean, Date |
name=='my friend' or name==friend_ |
Different |
!= |
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 the 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,B,'B A') |
Does not contain |
=notContains= |
string |
=notContains=(A,B,'B A') |
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='A B' |
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_. |
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 row, the list of user(s) and group(s) affected by the filter.
| It is possible not to expose this column by disabling it from the column choice settings. |
Expected syntax
columnName=operator=variable
| 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 the groups to which the user belongs. |
The value contains one of the groups to which the user belongs |
The value does not contain any of the groups to which the user belongs. |
|
The operator behaves like a %like% in a database. For example, if a user belongs to Admin and the authentication column contains the value Administrator, given that the value Admin is contained in the value Administrator, the user will be able to access the data. The example below details this behaviour 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 part of the Users group
| id | data | auth_group |
|---|---|---|
1 |
data1 |
Admin |
2 |
Data2 |
User Administrator |
3 |
Data3 |
User Admin |
4 |
Data4 |
Admin User |
Variable
auth_group=containsAllOf=@DcUserGroups
The filter allows the user to see only the rows in the data where the value in the Auth_group column contains all the values equal to the values of the groups to which he belongs.
-
John sees all the rows because the value "Admin" is included in the value "Administrator".
-
Alice sees lines 2 and 4
-
Cynthia doesn’t see any lines because "Users" is not a value included in "User".
To avoid including unwanted values, it is preferable 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.
columnName=operator=#@DcUserGroups#
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# |