Configure Data Exchange API endpoints
Edit on GitHubThis document describes how to create and configure the Data Exchange API endpoints.
The Data Exchange API lets you create endpoints to interact with any database tables through API. In this example, we are creating the /dynamic-data/countries
endpoint to interact with the spy_country
and spy_tax_rate
tables. When following the steps, adjust the data per your requirements.
Create and configure a Data Exchange API endpoint
To register an endpoint for interacting with entities in the database, you need to add a corresponding row to the spy_dynamic_entity_configuration
table. The table contains the configuration of dynamic entity endpoints and has the following columns:
COLUMN | SPECIFICATION |
---|---|
id_dynamic_entity_configuration | ID of the configuration. |
table_alias | An alias used in the request URL to refer to the endpoint. |
table_name | Name of the database table to operate on. |
is_active | Defines if the endpoint can be interacted with. |
definition | A JSON-formatted string containing the configuration details for each field in the table. |
created_at | Date and time when the configuration was created. |
updated_at | Date and time when the configuration was updated. |
You can optionally create a relation by adding new rows to spy_dynamic_entity_configuration_relation
and spy_dynamic_entity_configuration_relation_field_mapping
tables.
The spy_dynamic_entity_configuration_relation
contains the configuration of relations for dynamic entity endpoints and has the following columns:
COLUMN | SPECIFICATION |
---|---|
id_dynamic_entity_configuration_relation | ID of the configuration relation. |
fk_parent_dynamic_entity_configuration | Foreign key of the dynamic entity configuration for parent dynamic entity configuration ID. |
fk_child_dynamic_entity_configuration | Foreign key of the dynamic entity configuration for child dynamic entity configuration ID. |
name | Name of the dynamic entity relation. |
is_editable | Defines if the endpoint can be editable. |
spy_dynamic_entity_configuration_relation_field_mapping
contains the configuration of relation field mapping for dynamic entity endpoints and has the following columns:
COLUMN | SPECIFICATION |
---|---|
id_dynamic_entity_configuration_relation_field_mapping | ID of the configuration relation field mapping. |
fk_dynamic_entity_configuration_relation | Foreign key of the dynamic entity configuration relation for dynamic entity configuration relation ID. |
child_field_name | Foreign field key name for the child data table. |
parent_field_name | Reference field name for the parent data table. |
The following example shows a possible value of the spy_dynamic_entity_configuration.definition
field configured for the spy_country
table:
{
"identifier": "id_country",
"fields": [
{
"fieldName": "id_country",
"fieldVisibleName": "id_country",
"isEditable": false,
"isCreatable": false,
"type": "integer",
"validation": {
"isRequired": false
}
},
{
"fieldName": "iso2_code",
"fieldVisibleName": "iso2_code",
"type": "string",
"isEditable": true,
"isCreatable": true,
"validation": {
"isRequired": true,
"maxLength": 2,
"minLength": 2
}
}
]
}
and for spy_tax_rate
table:
{
"identifier": "id_tax_rate",
"fields": [
{
"fieldName": "id_tax_rate",
"fieldVisibleName": "id_tax_rate",
"isCreatable": true,
"isEditable": true,
"type": "integer",
"validation": { "isRequired": false }
},
{
"fieldName": "fk_country",
"fieldVisibleName": "fk_country",
"isCreatable": true,
"isEditable": true,
"type": "integer",
"validation": { "isRequired": false }
},
{
"fieldName": "name",
"fieldVisibleName": "name",
"isCreatable": true,
"isEditable": true,
"type": "string",
"validation": { "isRequired": true }
},
{
"fieldName": "rate",
"fieldVisibleName": "rate",
"isCreatable": true,
"isEditable": true,
"type": "float",
"validation": { "isRequired": true }
}
]
}
For configuration relations follow Configure Dynamic Data installation .
FIELD | DESCRIPTION |
---|---|
identifier | The name of the column in the table that serves as an identifier. It can be any chosen column from the table, typically used as a unique ID for each record. |
fields | An array containing the descriptions of the columns from the table. It defines the columns that are included for interaction. The API exposes and operates on the included columns. Columns that are not included in the array are inaccessible through API requests. |
fieldName | The name of the column in the database table. |
fieldVisibleName | The name used for interacting with the field through API requests. It’s a more user-friendly and descriptive name compared to the physical column name. |
type | The data type of the field. It specifies the expected data format for the field, enabling proper validation and handling of values during API interactions. |
isEditable | Defines if the field’s value can be changed. |
isCreatable | Defines if the field can be included in requests to provide an initial value during record creation. |
validation | Contains validation configurations. Proper validation ensures that the provided data meets the specified criteria. |
required | Defines if the field must be provided in API requests. |
maxLength | Defines the maximum length allowed for the field with a string type. It enforces a boundary, ensuring that the field’s value meet or doesn’t exceed the defined requirement. |
minLength | Defines the minimum length allowed for the field with a string type. It enforces a boundary, ensuring that the field’s value meets or exceeds the defined requirement. |
max | Defines the maximum value allowed for the field with an integer type. It enforces a boundary, ensuring that the field’s value meet or doesn’t exceed the defined requirement. Optional. |
min | Defines the minimum value allowed for the field with an integer type. It enforces a boundary, ensuring that the field’s value meets or exceeds the defined minimum requirement. Optional. |
-
We recommend setting
isEditable
andisCreatable
tofalse
for fields that serve as identifiers or keys, ensuring their immutability and preserving the integrity of the data model. -
For the fields with numerable values, an integer data type is a non-decimal number between -2147483648 and 2147483647 in 32-bit systems and, in 64-bit systems, between -9223372036854775808 and 9223372036854775807. If you need or anticipate values outside of this range, you can set the value as a string type.
-
The Data Exchange API supports the following types for the configured fields:
- boolean
- integer
- string
- decimal
Enable and configure the Data Exchange API endpoint in the Back Office
- In the Back Office, go to Data Exchange API Configuration.
- On the Data Exchange API Configuration page, click Create Data Exchange API configuration.
- In CREATE DATA EXCHANGE API CONFIGURATION pane, for TABLE NAME, select the table you want to configure the API for. In our example, it’s
spy_country
.
If you don’t see the needed table, it may be excluded from configuring.
- Click Create. This opens the EDIT DATA EXCHANGE API CONFIGURATION page.
- For RESOURCE NAME, enter the name of the endpoint you want to create. In our case, it’s
countries
. - Optional: To enable the endpoint after it’s configured, select IS ENABLED.
- Configure the fields for interactions per your requirements.
- Click Save. This opens the Data Exchange API Configuration page with the endpoint displayed in the list. Now you can send requests to this endpoint.
If everything is set up correctly, you can follow How to send request in Data Exchange API to discover how to request your API endpoint. Or if you’re in the middle of the integration process for the Data Exchange API follow Install the Data Exchange API to proceed with it.
Download Data Exchange API specification
You can download the specification of all the available endpoints, including the Data Exchange API endpoints, in the OpenAPI format. To download the specification, go to the Data Exchange API Configuration page, click Download API Specification. This initiates the download of the specification to your computer.
In case you’ve added new endpoints, the documentation will be automatically updated with the new information after a minute. The Download API Specification button is inactive during the documentation update process and becomes available again after one minute. There is a notification about this at the top of the page:
Next steps
Thank you!
For submitting the form