Managing Data Definitions with the REST API

These example calls execute CRUD operations on Data Definitions using cURL, a cross-platform tool for making HTTP calls. Feel free to use any REST client you know.

Adding Data Definitions

Get the siteId from the Site Menu → Configuration → Site Settings.

In this example, it’s 20123.

curl -i -X POST \
  http://localhost:8080/o/data-engine/v1.0/sites/20123/data-definitions \
  -H 'Authorization: Basic dGVzdEBsaWZlcmF5LmNvbTp0ZXN0' \
  -H 'Content-Type: application/json' \
  -d '{
    "dataDefinitionFields": [
        {
            "fieldType": "text",
            "name": "product"
        }
    ],
    "description": {
            "en_US": "Description"
    },
    "name": {
            "en_US": "Order"
    },
    "storageType":"json"
}'

Here you specify the endpoint for the data definitions API, passing in the siteId. Then you create a request body that includes

dataDefinitionFields: The example above is simple, with just a fieldType and a name element for one field. Here’s the complete list of elements that each field can have:

Property	Description
`customProperties`	these depend on the field type (listed below)
`defaultValue`	set a default value for a field
`fieldType`	the field type
`indexable`	set to `true` (default) or `false` to control whether the fields are indexed in the search engine
`label`	set a human readable label for each of the custom properties the fields has
`localizable`	can be set to `true` (default) or `false` to control whether the locale of the User is appended when he or she adds a data record
`name`	a required element that names the field (defaults to `string`)
`nestedDataDefinitionFields`	set of data definition fields
`repeatable`	set to `true` or `false` to control whether the field accepts multiple values per data record
`tip`	provide help text for the field’s properties

storageType: This must be set to "storageType":"json" in the current version of the API.

Each field has its own custom properties. Here is the complete list of fields and properties:

Custom properties for the checkbox field:

showAsSwitcher: set to true or false to control whether the checkbox is displayed as a switcher.
predefinedValue: provide a predefined value for the field.

Custom properties for the checkbox_multiple field:

inline: set to true or false to control whether the options are going to be shown inline or not.
options: set the options of the field.
showAsSwitcher: set to true or false to control whether the options are displayed as a switcher.
predefinedValue: provide a predefined value for the field.
readOnly: mark the field as Read IOnly, so that data cannot be written to it.
required: mark the field as required.
showLabel: display the label of the field.

Custom properties for the date field:

predefinedValue: provide a predefined value for the field.

Custom properties for the document_library field:

groupId: set the group id.
itemSelectorAuthToken: set the auth token.
lexiconIconsPath: set the icons path.

Custom properties for the editor field:

placeholder: set a placeholder value for the field.

Custom properties for the fieldset:

orientation: set the orientation in how the nested fields are going to be shown: horizontal or vertical. The default orientation is horizontal.

Custom properties for the grid field:

columns: set the options for the columns in the grid field.
rows: set the options for the rows in the grid field

Custom properties for the numeric field:

dataType: set if the number is going to be decimal or integer.
placeholder: set a placeholder for the field.
predefinedValue: provide a predefined value for the field.
readOnly: mark the field as Read IOnly, so that data cannot be written to it.
required: mark the field as required.
showLabel: display the label of the field.
tooltip: set a tooltip for the field.

Custom properties for the paragraph field:

text: set the text that populates the paragraph.

Custom properties for the radio field:

inline : set to true or false to control whether the options are shown inline or not.

options: set the options of the field.
predefinedValue: provide a predefined value for the field.
readOnly: mark the field as Read IOnly, so that data cannot be written to it.
required: mark the field as required.
showLabel: display the label of the field.

Custom properties for the select field:

dataSourceType: set how the options are populated; manually (manual), from a Data Provider (data-provider), or from Autofill (from-autofill).
multiple: set to true or false to control whether the field accepts more than one option as a value.
options: set the options.
predefinedValue: provide a predefined value for the field.
readOnly: mark the field as Read IOnly, so that data cannot be written to it.
required: mark the field as required.
showLabel: display the label of the field.

Custom properties for the text field:

autocompleteEnabled: set to true or false to control whether the field autocompletes the text input.
displayStyle: set the display style, as a single line (singleline) or as multiple lines (multiline).
options: set the options.
placeholder: set a placeholder for the field.
predefinedValue: provide a predefined value for the field.
readOnly: mark the field as Read IOnly, so that data cannot be written to it.
required: mark the field as required.
showLabel: display the label of the field.
tooltip: set a tooltip for the field.

For a complete view of the JSON structure of a data definitions, see the data-engine-rest-impl/rest-openapi.yaml file. For a more robust User Experience, copy the file contents into the Swagger Editor and get auto-generated Open API docs.

One your POST call is processed, a DataDefinition is returned in the body. You will need its id to create data record collections for the definition’s records.

HTTP/1.1 200 
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1
Set-Cookie: JSESSIONID=19FBDA81A72F8EA1F9668A153E9F2FBA; Path=/; HttpOnly
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Cache-Control: private, no-cache, no-store, must-revalidate
Pragma: no-cache
Set-Cookie: COOKIE_SUPPORT=true; Max-Age=31536000; Expires=Fri, 22-May-2020 20:18:15 GMT; Path=/; HttpOnly
Set-Cookie: GUEST_LANGUAGE_ID=en_US; Max-Age=31536000; Expires=Fri, 22-May-2020 20:18:15 GMT; Path=/; HttpOnly
Date: Thu, 23 May 2019 20:18:16 GMT
Content-Type: application/json
Content-Length: 307

{
  "dataDefinitionFields" : [ {
    "fieldType" : "text",
    "indexable" : true,
    "localizable" : false,
    "name" : "product",
    "repeatable" : false
  } ],
  "dateCreated" : "2019-05-23T20:18:16Z",
  "dateModified" : "2019-05-23T20:18:16Z",
  "id" : 39108,
  "siteId" : 20123,
  "userId" : 20129
}

Here you can see that some information was added by the data engine itself:

id is a number generated by the system.

indexable is set to true by default, so the field is indexed in the search engine.

localizable is set to false by default.

repeatable is set to false by default, so submitting the same field multiple times for the same data record is not allowed.

dateCreated and dateModified: the data engine updates this metadata when the data definition is first created and when it’s updated, respectively.

userId is set to the numeric ID of the User that created the definition.

Before we move on, it’s important to understand the relationship between the data definition and the information you’ll collect from Users, as a data record. A data record must conform to the fields defined in this data definition creation step. Therefore, when you add a data record in a later step your request must use a dataRecordValues structure like this:

    "dataRecordValues": {

        "product": "Bicycle"
    }

Retrieving Data Definitions

In addition to adding data definitions, you can make GET calls to the service. Retrieve all the data definitions in a Site by passing in the Site ID (20123 here):

curl -i -X GET \
  http://localhost:8080/o/data-engine/v1.0/sites/20123/data-definitions \
  -H 'Authorization: Basic dGVzdEBsaWZlcmF5LmNvbTp0ZXN0' \
  -H 'Content-Type: application/json' \

Deleting Data Definitions

Data definitions can also be deleted with a DELETE request. You’ll need the data definition ID:

curl -i -X DELETE \
  http://localhost:8080/o/data-engine/v1.0/data-definitions/39108 \
  -H 'Authorization: Basic dGVzdEBsaWZlcmF5LmNvbTp0ZXN0' \
  -H 'Content-Type: application/json' \

Deleting a data definition also deletes all associated Data Record Collections, Data Records, and Data Layouts.

« Introduction to Data EngineManaging Data Record Collections with the REST API »

Help Center

Products

Resources

Security

Support

Documentation

Adding Data Definitions

Retrieving Data Definitions

Deleting Data Definitions