Built-in RESTful services

Dernière publication : Aug 10, 2026
Related information

Introduction

The architecture used is called ROA (Resource-Oriented Architecture), it can be an alternative to SOA (Service-Oriented Architecture). The chosen resources are readable and/or writable by third-party systems, according to the request content.
The HATEOAS approach of the built-in RESTful services also allows to experience an intuitive and straightforward navigation, which implies that the data details could be obtained through a link.
Note:
All operations are stateless.

Request

This chapter describes the elements to use in order to build a conform REST request, such as: the HTTP method, the URL format, the header fields and the message body.
See also:

HTTP method

Considered HTTP methods for built-in RESTful services, are:
  • GET: used to select master data defined in the URL (the URL size limit depends on the application server or on the browser, that must be lower than or equal to 2KB).
  • POST: used to insert one or more records in a table or to select the master data defined in the URL (the size limit is 2MB or more depending on the application server. Each parameter is limited to a value containing 1024 characters).
  • PUT: used to update the master data defined in the URL.
  • DELETE: used to delete either the record defined in the URL or multiple records defined with the table URL and the record table in the message body.

URL

REST URL contains:
http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/{categoryVersion}/{specificPath}[:{extendedAction}]?{queryParameters}
Where:
  • <ebx-dataservices> corresponds to the 'ebx-dataservices.war' web application's path. The path is composed by multiple, or none, URI segments followed by the web application's name.
  • {category} corresponds to the operation category.
  • {categoryVersion} corresponds to the category version: current value is v1.
  • {specificPath} corresponds to a specific path inside the category.
  • {extendedAction} corresponds to the extended action name (optional).
  • {queryParameters} corresponds to common or dedicated operation parameters passed by the URL.

Operation category

It specializes the operation, it is added in the path of the URL in {category} and it takes one of the following values:
admin
Administration operations reserved to administrators.
For more information, see: Administration operations.
auth
Manage token authentication method.
For more information, see: Token authentication operations and Token Authentication Scheme.
data
Lists dataset content, requests a table, a record or a field record content, including modified operations on dataset node, table, record and record field.
For more information, see: Data operations.
history
Lists history dataset content, requests a history table, a history of a record or a history record.
For more information, see: Data operations.
See also:

Header fields

These header field definitions are used by TIBCO EBX®.
Accept
Used to specify content types by order of preference to be used in the response, the first supported one will be chosen and specified in the response header Content-Type. Currently, the only supported one is application/json. If none is supported, the result depends on the ebx.dataservices.rest.request.checkAccept property:
  • If true, an HTTP error response is returned with code 406.
  • If false, the response is returned with the default content type, that is application/json.
See also:
Accept-Language
Used for specifying the preferred locale for the response. The supported locales are defined in the schema model.
If none of the preferred locale are supported, the default locale for the current model is used.
Authorization
Used for 'Basic Authentication Scheme' and 'Token Authentication Scheme' methods, otherwise the request is rejected.
See also:
Content-Type
Used to specify the request body media type. The supported types are application/json and application/x-www-form-urlencoded. The request value is checked and if it is not supported, then an HTTP error message is returned with the code 415 (Unsupported media type).
See also:
X-Requested-With
If present and in case of authentication failure, prevents the addition of the WWW-Authenticate header in the response.
See also:
See RFC2616 for more information about HTTP Header Field Definitions.

Common parameters

These optional parameters are available for all data service operations.
Parameter
Description
disableRedirectionToLastBroadcast
This parameter only has impact on a D3 architecture.
If true, access to a delivery dataspace on a D3 primary node is not redirected to the last broadcast snapshot. Otherwise, access to such a dataspace is always redirected to the last broadcast snapshot.
If the specified dataspace is not a delivery dataspace on a D3 primary node, this parameter is ignored.
Boolean type value. If this parameter is not present, the default is false (redirection to a D3 master enabled), unless the configuration property ebx.dataservices.disableRedirectionToLastBroadcast.default has been set.
See also:
indent
Specifies if the response should be indented, to be easier to read for a human.
Boolean type, default value is false.

Message body

It contains the request data using the JSON format, see JSON Request body.
Note:
Requests may define a message body only when using POST or PUT HTTP methods.

Response

This chapter describes the responses returned by built-in RESTful services.
  • See Exception handling for details on standard error handling (where the HTTP code is greater than or equal to 300).

Header fields

These header field definitions are used by EBX®.
Content-Language
Indicates the locale used in the response for labels and descriptions.
Content-Type
Indicates the response body content type.
Location
If a new record has been successfully inserted, the query URL for this record is returned by this field.
WWW-Authenticate
This header field is added to the HTTP response when authentication fails with the 401 (Unauthorized) HTTP code. Its value consists of a list with at least one authentication method applicable to the request URI. It is present if and only if the following conditions are verified:
  • the 'Basic Authentication Scheme' method is enabled and
  • the X-Requested-With HTTP header is not present.
If the client is able to interpret the authentication method, it is possible to resubmit the request providing the appropriate credentials.
The administration property ebx.dataservices.rest.auth.tryBasicAuthentication must be set to true.
See also:

HTTP codes

HTTP code
Description
200 (OK)
The request has been successfully handled.
201 (Created)
A new record has been created, in this case, the header field Location is returned with its resource URL.
204 (No content)
The request has been successfully handled but no response body is returned.
400 (Bad request)
the request URL or body is not well-formed or contains invalid content.
401 (Unauthorized)
Authentication has failed.
403 (Forbidden)
Permission was denied to read or modify the specified resource for the authenticated user.
This error is also returned when the user:
  • is not allowed to modify a field mentioned in the request message body.
  • is not allowed to access the REST connector.
    For more details, see Global permissions.
404 (Not found)
The resource specified in the URL cannot be found.
406 (Not acceptable)
Content type defined in the request's Accept parameter is not supported. This error can be returned only if the EBX® property ebx.rest.request.checkAccept is set to true.
409 (Conflict)
A concurrent modification has occurred.
See also:
415 (Unsupported media type)
The request content is not supported, the request header value Content-Type is not supported by the operation.
422 (Unprocessable entity)
The new resource's content cannot be accepted for semantic reasons.
500 (Internal error)
Unexpected error thrown by the application. Error details can usually be found in EBX® logs.

Message body

The response body content's format depends on the HTTP code value:
  • HTTP codes from 200 included to 300 excluded: the content format depends on the associated request (JSON samples).
    With the exception of code 204 (No content).
  • HTTP codes greater than or equal to 300: the content describes the error. See JSON for details on the format.

Administration operations

Administration operations are related to:
  • the administration category.
  • the administration dataspaces accessible through the data category.
Note:
administration category and administration dataspaces can only be used by administrators.

Directory operations

The EBX® default directory configuration is manageable with built-in RESTful services. The users and roles tables, the mailing lists and other objects are concerned. For more information, see Users and roles directory.
Note:
Triggers are present on the directory's tables, ensuring the data consistency.
The URL format is:
http[s]://<host>[:<port>]/<ebx-dataservices>/rest/data/v1/Bebx-directory/ebx-directory

Directory configuration operations

The EBX® default directory configuration is manageable like dataset nodes. It can be accessed and modified through the data category operations. Each field is self-described when metadata is requested.
See select and update operations for more information.

Mailing lists operations

There are two default mailing lists that can be configured in the EBX® directory: one for everybody and one for administrators. These lists can be handled like dataset nodes through the data category operations.
See select and update operations for more information.

Directory users operations

Users can be manipulated like records of the data category using the operations of the latter. For security purposes, an administrator cannot delete himself. The user's salutation must be chosen among the ones available in the 'salutations' table.
See select, update, insert and delete operations for more information.

Directory roles operations

Roles are records of the data category and can be managed with its operations. EBX® roles are assigned to users through the 'usersRoles' association table. 'usersRoles' is automatically fed when the directory is administered through the user interface. However, it is not the case through data services and role assignments require manual operations. Roles inclusions are specified in the 'rolesInclusions' association table. As for the 'usersRoles' table, the management of roles inclusions requires manual operations. Each table is self-descriptive when metadata is requested.
See select, update, insert and delete operations for more information.

User interface operations

The EBX® user interface can be opened or closed to users for maintenance needs. Handled information is similar to what is contained in the UI tab 'Administration' > 'User interface configuration' > 'Advanced perspective' > 'Graphical interface configuration' > 'Application locking'.
URL format is:
http[s]://<host>[:<port>]/<ebx-dataservices>/rest/data/v1/Bebx-manager/ebx-manager/domain/toolStatus
See also:

Retrieve user interface state

User interface status and the unavailability message are accessible like dataset nodes.
See Select operation and the JSON example, for more information.

Open or close user interface

User interface status and the unavailability message can be modified like dataset nodes using the update operation. To open the user interface set the content of toolStatus to true, or to false to close it.
See Update operation and the JSON examples, for more information.

System information operation

This operation returns system information on the EBX® server. This is accepted for GET and POST HTTP methods. Warning: no update will be possible in the POST HTTP method because the request body is ignored. The information returned is the same as the information contained in the log header kernel.log or in the UI tab 'Administration' > 'System Information'. The response contains several keys, labels, and values representing the configuration and status of EBX®. The mode of representation of the response may be flat or hierarchical.
http[s]://<host>[:<port>]/<ebx-dataservices>/rest/admin/v1/systemInformation
See also:

Parameters

The following parameter is applicable.
Parameter
Description
systemInformationMode
Specifies the returned mode:
  • flat: A flat representation under the following information groups: bootInfoEBX, repositoryInfo and bootInfoVM.
  • hierarchical: A hierarchical representation.
String type, default value is flat.

HTTP codes

HTTP code
Description
200 (OK)
The system information was successfully returned.
400 (Bad request)
The request is not correct, it contains one of the following errors:
  • the HTTP method is not GET nor POST,
  • the HTTP parameter systemInformationMode is not correct,
  • the operation is not supported.
  • the request path is invalid.
403 (Forbidden)
The user is not an administrator.

Response body

It is returned, if and only if, the HTTP code is 200 (OK). The content structure depends on the provided parameter systemInformationMode or its default value.
See the JSON example of the flat representation.
See the JSON example of the hierarchical representation.

Token authentication operations

These operations allow to create or revoke an authentication token. Authentication tokens have a timeout period. If a token is not used to access the EBX® server within this period, it will automatically be revoked. This timeout period is refreshed on each access to EBX® server.
Note:
The token timeout is modifiable through the administration property ebx.dataservices.rest.auth.token.timeout (the default value is 30 minutes).

Create token operation

This operation requires using the POST HTTP method with a request containing the user's credentials and, optionally, session parameters.
URL format is:
http[s]://<host>[:<port>]/<ebx-dataservices>/rest/auth/v1/token:create

Message body

A message body must be defined in the HTTP request. It necessarily contains one of the following set of data:
  • A login and a password value. Both JSON attributes are mandatory and of String types.
    See Directory.authenticateUserFromLoginPassword for more information.
  • The specific JSON attribute set to true. When activated, this flag allows to performed a user authentication against the whole HTTP request. Warning, even if login and password attributes are defined in the JSON request's body, setting specific to true lead to a specific user authentication.
    See Directory.authenticateUserFromHttpRequest for more information.
See the JSON examples of a token creation request.

HTTP codes

HTTP code
Description
200 (OK)
The token was successfully created.
400 (Bad request)
For one of the following reasons:
  • the syntax is not correct,
  • the HTTP method is not POST,
  • the operation is not supported.
401 (Unauthorized)
For one of the following reasons:
  • The login and/or password is/are incorrect.
  • Authentication data for other methods is defined.
422 (Unprocessable entity)
For one of the following reasons:
  • PasswordMustChange: The password must be changed (only available with the default directory). See Change password operation.
  • RestrictedAccess: User access is closed for maintenance or other actions (reserved to administrators).

Response body

If the HTTP code is 200 (OK), the body holds the token value and its type.
See the JSON example of a token creation response.
The token can later be used to authenticate a user by setting the HTTP-Header Authorization accordingly.
See also:

Change password operation

This operation modifies the password of an existing user account. It can be used in an authenticated context: login parameter, if present, is checked against the current session or taken from it, if absent. It could also be used in an unauthenticated context, for example when the Create token operation aborts with the HTTP code 422 (Unprocessable entity) with reason: PasswordMustChange.
It requires the use of:
  • the EBX® default directory
  • the POST HTTP method
  • the message body containing the structure specified below
URL format is:
http[s]://<host>[:<port>]/<ebx-dataservices>/rest/auth/v1/user:changePassword

Message body

The message body must be defined in the request. It necessarily contains a password and a passwordNew, the login is optional (all are String).
See the JSON example of a password change and token creation request.

HTTP codes

HTTP code
Description
204 (No content)
The password has been changed.
400 (Bad request)
For one of the following reasons:
  • the EBX® default directory is required,
  • the syntax is not correct,
  • the HTTP method is not POST,
  • the provided login and the user's session one mismatch
  • the operation is not supported.
401 (Unauthorized)
For the following reason:
  • The login and/or password is/are incorrect.
422 (Unprocessable entity)
For one of the following reasons:
  • PasswordChangeAbort: passwordNew is empty.
  • PasswordChangeAbort: passwordNew is equal to password.
  • PasswordChangeAbort: password is incorrect.
  • RestrictedAccess: User access is closed for maintenance or other actions (reserved to administrators).

Response body

If HTTP code 204 (No content) is returned, then the password has been modified.

Revoke token operation

This operation requires using the POST HTTP method. No message body is needed.
URL format is:
http[s]://<host>[:<port>]/<ebx-dataservices>/rest/auth/v1/token:revoke

Header fields

Authorization
This field is required, tokenType and accessToken fields must have the values returned from the "token create" operation. 
> Authorization: <tokenType> <accessToken>

HTTP codes

HTTP code
Description
204 (No content)
The token has been revoked successfully.
400 (Bad request)
For one of the following reasons:
  • the configuration is not activated,
  • the syntax is incorrect,
  • the HTTP method is not POST,
  • the operation is not supported.
401 (Unauthorized)
Authentication has failed.

Data operations

Operations from the data operation category concern the datasets, the dataset fields, tables, records or record fields.
Operations from the history category and concern historized content from datasets, tables, records or the record fields.

Select operation

Select operation may use one of the following methods:
  • GET HTTP method,
  • POST HTTP method without message body or
  • POST HTTP method with message body and optionally session parameters.
    URL formats are:
  • Dataset tree, depending on operation category:
    The data category returns the hierarchy of the selected dataset, this includes group and table nodes.
    The history category returns the hierarchy of the selected history dataset, this includes the pruned groups for history table nodes only.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}
    Note:
    Terminal nodes and sub-nodes are not included.
  • Dataset node: the data category returns the terminal nodes contained in the selected node.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/data/v1/{dataspace}/{dataset}/{pathInDataset}
    Note:
    Not applicable with the history category.
  • Table, depending on operation category:
    the data category returns the table content and/or metadata, current page records and URLs for pagination.
    The history category returns the history table content and/or metadata, current page records and URLs for pagination.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}
    See also:
  • Record, depending on operation category:
    the data category returns the record content and/or metadata.
    The history category returns history record content and/or metadata.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}/{encodedPrimaryKey}
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}?primaryKey={xpathExpression}
    Note:
    The record access by the primary key ( primaryKey parameter) is limited to its root node. It is recommended to use the encoded primary key, available in the details field in order to override this limitation. Similarly, for a history record, use the encoded primary key, available in the historyDetails field.
  • Field, depending on operation category:
    the data category returns the field record content where structure depends on its type.
    The history category returns the field history record content where structure depends on its type.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}/{encodedPrimaryKey}/{pathInRecord}
    Note:
    The field must be either an association node, a selection node, a terminal node or above.
    Where:
  • {category} corresponds to the operation category.
  • {dataspace} corresponds to B followed by the dataspace identifier or to V followed by the snapshot identifier.
  • {dataset} corresponds to the dataset identifier.
  • {pathInDataset} corresponds to the path of the dataset node, that can be a group node or a table node.
  • {encodedPrimaryKey} corresponds to the encoded representation of the primary key.
    See also:
  • {xpathExpression} corresponds to the record primary key, using the XPath expression.
  • {pathInRecord} corresponds to the path starting from the table node.

Parameters

The following parameters are applicable to the select operation.
Parameter
Description
includeContent
Includes the content field with the content corresponding to the selection.
Boolean type, default value is true.
includeDetails
Includes the details field in the metadata and the response, for each indirect reachable resource. The returned value corresponds to its URL resource.
Type Boolean, default value is true.
See also:
includeHistory
Includes those fields for a historized content:
  • The history property in the metadata. The returned value corresponds to a boolean value.
  • The historyDetails property in the content and for each indirectly reachable resource. This point is coupled to the includeDetails parameter. The returned value corresponds to its URL resource.
Boolean type, default value is false.
Note:
The includeHistory parameter is ignored in the history category, the default value is true.
See also:
includeLabel
Includes the label field associated with each simple type content.
Possible values are:
  • yes: the label is included for the foreign key, enumeration, record and selector values.
  • all: the label field is included, as for the yes value and also for the Content of simple type.
    See also:
  • no: the label field is not included (integration use case).
String type, default value is yes.
Note:
The label field is not included if it is equal to the content field.
includeMeta
Includes the meta field corresponding to the description of the structure returned in the content field.
Boolean type, default value is false.
See also:
includeMergeInfo
Includes the merge_info corresponding to a field of the technical data of an history transaction and has a potentially high access cost.
Boolean type, default value is true.
Note:
This parameter is ignored with the data category.
See also:
includeSelector
Includes the selector field in the response, for each indirect reachable resource. The returned value corresponds to its URL resource.
Type Boolean, default value is true.
See also:
includeSortCriteria
Includes the sortCriteria field corresponding to the list of sort criteria applied.
The sort criteria parameters are added by using:
Boolean type, default value is false.
Example JSON
includeTechnicals
Includes the internal technical data.
Boolean type, default value is false.
See also:
Note:
This parameter is ignored with the history category.
includeValidation
Includes the validation report corresponding to the selection.
Boolean type, default value is false.
Note:
This parameter is ignored with the history category.
See also:

Table parameters

The following parameters are applicable to tables, associations and selection nodes.
Parameter
Description
filter
XPath predicate expression defines the field values to which the request is applied. If empty, all records will be retrieved.
String type value.
Note:
The history code operation value is usable with ebx-operationCode path field from the meta section associated with this field.
historyMode
Specifies the filter context applied on table.
String type, possible values are:
  • CurrentDataSpaceOnly: history in current dataspace
  • CurrentDataSpaceAndAncestors: history in current dataspace and ancestors
  • CurrentDataSpaceAndMergedChildren: history in current dataspace and merged children
  • AllDataSpaces: history in all dataspaces
The default value is CurrentDataSpaceOnly.
See also:
Note:
This parameter is ignored with the data category.
includeOcculting
Includes the records in occulting mode.
Boolean type, default value is false.
primaryKey
Search a record by a primary key, using the XPath expression. The XPath predicate expression should only contain field(s) of the primary key and all of them. Fields are separated by the operator and. A field is represented by one of the following possibilities according to its simple type:
  • For the date, time or dateTime types: use the date-equal(path, value)
  • For other types: indicate the path, the = operator and the value.
Example with a composed primary key: ./pk1i=1 and date-equal(./pk2d,'2015-11-13')
The response will only contain the corresponding record, otherwise an error is returned. Consequently, the other table parameters are ignored (as filter, viewPublication, sort, etc.)
String type value.
pageFirstRecordFilter
Deprecated since version 5.9.0, replaced by pageRecordFilter
pageRecordFilter
Specifies the record XPath predicate expression filter of the page.
String type value.
pageAction
Specifies the pagination action to perform from page defined by pageRecordFilter.
String type, possible values are:
  • first
  • previous
  • next
  • last
See also:
pageSize
Specifies the number of records per page.
Integer type, default value is based on the user preferences.
String type, the unbounded value can be defined to return all records. Only for this case, no pagination context is returned.
sort
Specifies that the operation result will be sorted according to the specified criteria. The criteria are composed of one or more criteria, the result will be sorted by priority from the left. A criterion is composed of the field path and, optionally, the sorting order (ascending or descending, on value or on label). This parameter can be combined with:
  1. the sortOnLabel parameter as a new criteria added after the sort.
  2. the viewPublication parameter as a new criteria added after the sort.
The value structure is as follows:
<path1>:<order>;...;<pathN>:<order>
Where:
  • <path1> corresponds to the field path in priority 1.
  • <order> corresponds to the sorting order, with one of the following values:
    • asc: ascending order on value (default),
    • desc: descending order on value,
    • lasc: ascending order on label,
    • ldesc: descending order on label.
String type, the default value orders according to the primary key fields (ascending order on value).
Note:
The history code operation value is usable with the ebx-operationCode path field from the meta section associated with this field.
See also:
sortOnLabel
Specifies that the operation result will be sorted according to the record label. This parameter can be combined with:
  1. the sort parameter as a new criteria added before the sortOnLabel.
  2. the viewPublication parameter as a new criteria added after the sortOnLabel.
The value structure is as follows:
<order>
Where:
  • <order> corresponds to the sorting order, with one of the following values:
    • lasc: ascending order on label,
    • ldesc: descending order on label.
The behavior of this parameter is described in the section defaultLabel.
String type value.
See also:
viewPublication
Specifies the name of the published view. This parameter can be combined with:
  1. the filter parameter as the logical and operation.
  2. the sort parameter as a new criteria added before the viewPublication.
  3. the sortOnLabel parameter as new criteria added before the viewPublication.
The behavior of this parameter is described in the section EBX® as a Web Component.
String type value.

Selector parameters

The following parameters are only applicable to fields that return an enumeration, foreign key or osd:resource (Example JSON). By default, a pagination mechanism is enabled.
Parameter
Description
selector
Specifies whether:
  • true: returns all possible values (includes their labels)
  • false: returns the current values for the current field.
Boolean type, default value is false.
Note:
This parameter is ignored with the history category.
firstElementIndex
Specifies the index of the first element returned by the selector. Must be an integer higher than or equal to 0.
Integer type, default value is 0.
pageSize
Specifies the number of elements per page.
Integer type, default value is based on the user preferences.
String type, the unbounded value can be defined to return all values. Only for this case, no pagination context is returned.
selectorFilter
Specifies the filter of the selector.
String type value, the syntax complies with the Text search.

HTTP codes

HTTP code
Description
200 (OK)
The selected resource is successfully retrieved.
400 (Bad request)
The request is incorrect. This occurs when:
  • The selected field in a record or a dataset is sub-terminal,
  • The XPath predicate of the filter parameter is malformed or contains unfilterable nodes.
  • The XPath predicate of the primaryKey parameter is malformed or is not a record primary key.
  • The sort criteria of the sort parameter have an invalid syntax or contain unsortable nodes.
  • pageAction parameter value is not included in allowed values, or pageRecordFilter is malformed or non-existent when selecting next or previous page.
  • pageSize parameter value is below 2, or is a string different from unbounded.
  • The table view for the viewPublication parameter is either hierarchical, non-existent or non-published.
  • The selector parameter is used for a non-enumerated node, or the firstElementIndex is negative, higher than or equal to the number of values.
403 (Forbidden)
The selected resource is hidden for the authenticated user.
404 (Not found)
The selected resource is not found.

Response body

After a successful dataset, table, record or field selection, the result is returned in the response body. The content depends on the provided parameters and selected data.
Example: JSON.

Insert operation

Insert operation uses the POST HTTP method. A body message is required to specify data. This operation supports the insertion of one or more records in a single transaction. Moreover, it is also possible to update record(s) through parameterization.
  • Record: insert a new record or modify an existing one in the selected table.
  • Record table: insert or modify one or more records in the selected table, while securing a consistent answer. Operations are executed sequentially, in the order defined on the client side. When an error occurs during a table operation, all updates are cancelled and the client receives an error message with detailed information.
http[s]://<host>[:<port>]/<ebx-dataservices>/rest/data/v1/{dataspace}/{dataset}/{pathInDataset}
Where:
  • {dataspace} corresponds to B followed by the dataspace identifier or to V followed by the snapshot identifier.
  • {dataset} corresponds to the dataset identifier.
  • {pathInDataset} corresponds to the path of the table node.

Parameters

The following parameters are applicable with the insert operation.
Parameter
Description
includeDetails
Includes the details field in the answer for access to the details of the data. The returned value corresponds to its URL resources.
Type Boolean, the default value is false.
Note:
Only applicable on the record table.
includeForeignKey
Includes the foreignKey field in the answer for each record. The returned value corresponds to the value of a foreign key field that was referencing this record.
Boolean type, the default value is false.
Note:
Only applicable on the record table.
includeLabel
Includes the label field in the answer for each record.
Possible values are:
  • yes: the label field is included.
  • no: the label field is not included (use case: integration).
String type, the default value is no.
Note:
Only applicable on the record table.
updateOrInsert
Specifies the behavior when the record to insert already exists:
  • If true: the existing record is updated with new data.
    For a request on a record table, the code field is added to the report in order to specify if this is an insert 201 or an update 204.
  • If false (default value): a client error is returned and the operation is aborted.
Boolean type value.
byDelta
Specifies the behavior for setting value of nodes that are not defined in the request body. This is described in the Update modes section.
Boolean type, the default value is true.
Note:
Applicable on record in update mode and if the updateOrInsert parameter is true.
blockingConstraintsDisabled
Specifies whether blocking constraints are ignored, if so, the operation is committed regardless of the validation error created, otherwise, the operation would be aborted.
Boolean type, default value is false.
See Blocking and non-blocking constraints for more information.

Message body

The request must define a message body. The format depends on the inserted object type:
  • Record: similar to the select operation of a record but without the record's header (example JSON).
  • Record table: Similar to the select operation on a table but without the pagination information (example JSON).
See also:

HTTP codes

HTTP code
Description
200(OK)
If the request relates to a record table.
The insert request was applied successfully, an optional report is returned in the response body.
201 (Created)
If the request relates to a record.
A new record has been created, in this case, the header field Location is returned with its resource URL.
204 (No content)
If the request relates to a record.
Only available if updateOrInsert is true, an existing record has been successfully updated, in this case, the header field Location is returned with its resource URL.
400 (Bad request)
The request is incorrect. This occurs when the body message structure does not comply with what was mentioned in Message body.
403 (Forbidden)
Authenticated user is not allowed to create a record or the request body contains a read-only field.
404 (Not found)
The selected resource is not found.
409 (Conflict)
Concurrent modification, only available if updateOrInsert is true, the Optimistic locking is activated and the content has changed in the meantime, it must be reloaded before update.
422 (Unprocessable entity)
The request cannot be processed. This occurs when:
  • A blocking validation error occurs (only available if blockingConstraintsDisabled is false).
  • The record cannot be inserted because a record with the same primary key already exists (only available if updateOrInsert is false).
  • The record cannot be inserted because the definition of the primary key is either non-existent or incomplete.
  • The record cannot be updated because the value of the primary key cannot be modified.

Response body

The response body format depends on the inserted object type:
  • Record: is empty if the operation was executed successfully. The header field Location is returned with its URL resource.
  • Record table: (optional) contains a table of element(s), corresponding to the insert operation report (example JSON). This report is automatically included in the response body, if at least one of the following options is set:
    • includeForeignKey
    • includeLabel
    • includeDetails
See also:

Update operation

This operation allows the modification of a single dataset or record. The PUT HTTP method must be used. Available URL formats are:
  • Dataset node: modifies the values of terminal nodes contained in the selected node.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/data/v1/{dataspace}/{dataset}/{pathInDataset}
  • Record: modifies the content of selected record.
    Note:
    Also available for POST HTTP methods. In this case, the URL must correspond to the table by setting the parameter updateOrInsert to true.
  • Field: modifies the field content.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/data/v1/{dataspace}/{dataset}/{pathInDataset}/{encodedPrimaryKey}/{pathInRecord}
    Note:
    The field must be either a terminal node or above.
    Where:
  • {dataspace} corresponds to B followed by the dataspace identifier or to V followed by the snapshot identifier.
  • {dataset} corresponds to the dataset identifier.
  • {pathInDataset} corresponds to the path of the dataset node:
    • For dataset node operations, this must be any terminal node or above except table node,
    • For record and field operations, this corresponds to the table node.
  • {encodedPrimaryKey} corresponds to the encoded representation of the primary key.
    See also:
  • {pathInRecord} corresponds to the path starting from the table node.

Parameters

Here are the parameters applicable with the update operation.
Parameter Description
blockingConstraintsDisabled Specifies whether blocking constraints are ignored, if so, the operation is committed regardless of the validation error created, otherwise, the operation would be aborted. Boolean type, default value is false. See Blocking and non-blocking constraints for more information.
byDelta Specifies the behavior for setting value of nodes that are not defined in the request body. This is described in the Update modes section. Boolean type, the default value is true.
checkNotChangedSinceLastUpdateDate Timestamp in datetime format used to ensure that the record has not been modified since the last read. Also see the Optimistic locking section. DateTime type value.

Message body

The request must define a message body.
The structure is the same as for:
  • the dataset node (sample JSON),
  • the record (sample JSON),
  • the record fields (sample JSON),
depending on the updated scope, by only keeping the content entry.
See also:

HTTP codes

HTTP code
Description
204 (No content)
The record, field or dataset node has been successfully updated.
400 (Bad request)
The request is incorrect. This occurs when the body request structure does not comply.
403 (Forbidden)
Authenticated user is not allowed to update the specified resource or the request body contains a read-only field.
404 (Not found)
The selected resource is not found.
409 (Conflict)
Concurrent modification, the Optimistic locking is activated and the content has changed in the meantime, it must be reloaded before the update.
422 (Unprocessable entity)
The request cannot be processed. This occurs when:
  • A blocking validation error occurs (only available if blockingConstraintsDisabled is false).
  • The record cannot be updated because the value of the primary key cannot be modified.

Delete operation

The operation uses the DELETE HTTP method.
Two URL formats are available:
  • Record: delete a record specified in the URL.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/data/v1/{dataspace}/{dataset}/{pathInDataset}/{encodedPrimaryKey}
  • Record table: deletes several records in the specified table, while providing a consistent answer. This mode requires a body message containing a record table. The deletions are executed sequentially, according to the order defined in the table. When an error occurs during a table operation, all deletions are cancelled and an error message is displayed with detailed information.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/data/v1/{dataspace}/{dataset}/{pathInDataset}
    Where:
  • {dataspace} corresponds to B followed by the dataspace identifier or to V followed by the snapshot identifier.
  • {dataset} corresponds to the dataset identifier.
  • {pathInDataset} corresponds to the path of the table node.
  • {encodedPrimaryKey} corresponds to the encoded representation of the primary key.
    See also:
    In a child dataset context, this operation modifies the inheritanceMode property value of the record as follows:
  • A record with inheritance mode set to inherit or overwrite becomes occult.
  • A record with inheritance mode set to occult becomes inherit if the inheritIfInOccultingMode operation parameter is set to true or is undefined, otherwise there is no change.
  • A record with inheritance mode set to root is simply deleted.
See also:

Parameters

Here are the following parameters applicable with delete operation.
Parameter Description
includeOcculting Includes occulted records. Boolean type, the default value is false.
inheritIfInOccultingMode Deprecated since version 5.8.1 While it remains available for backward compatibility reasons, it will eventually be removed in a future version. Inherits the record if it is in occulting mode. Boolean type, the default value is true.
checkNotChangedSinceLastUpdateDate Timestamp in datetime format used to ensure that the record has not been modified since the last read. Also see the Optimistic locking section. DateTime type value.
blockingConstraintsDisabled Specifies whether blocking constraints are ignored, if so, the operation is committed regardless of the validation error created, otherwise, the operation would be aborted. Boolean type, default value is false. See Blocking and non-blocking constraints for more information.

Message body

The request must define a message body only when deleting several records:
  • Record table: The message contains a table of elements related to a record, with for each element one of the following properties:
    • details: corresponds to the record URL, it is returned by the select operation.
    • primaryKey: corresponds to the primary key of the record, using the XPath expression.
    • foreignKey: corresponds to the value that a foreign key would have if it referred to a record.
    See also:
    Example JSON.

HTTP codes

HTTP code
Description
200 (OK)
The operation has been executed successfully. A report is returned in the response body.
400(Bad request)
The request is incorrect. This occurs when:
  • the structure of the message body does not comply with Message body.
  • the message body contains a record table while the URL specifies a record.
403 (Forbidden)
Authenticated user is not allowed to delete or occult the specified record.
404 (Not found)
The selected record is not found. In the child dataset context, it should be necessary to use the includeOcculting parameter.
409 (Conflict)
Concurrent modification, The Optimistic locking is activated and the content has changed in the meantime, it must be reloaded before deleting the record.
The parameter value checkNotChangedSinceLastUpdateDate exists but does not correspond to the actual last update date of the record.
422 (Unprocessable entity)
Only available if blockingConstraintsDisabled is false, the operation fails because of a blocking validation error.

Response body

After a successful record deletion or occulting, a report is returned in the response body. It contains the number of deleted, occulted and inherited record(s).
Example JSON.

Count operation

Count operation may use one of the following methods:
  • GET HTTP method,
  • POST HTTP method without message body or
  • POST HTTP method with message body but without content field on root.
    The URL formats are:
  • Dataset node: the data category returns the number of terminal nodes contained in the selected node.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/data/v1/{dataspace}/{dataset}/{pathInDataset}?count=true
    Note:
    Not applicable with the history category.
  • Table depending on the operation category:
    the data category returns the number of table records.
    The history category returns the number of table history records.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}?count=true
  • Field depending on the operation category:
    the data category counts the record fields.
    The history category counts the history record field.
    http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}/{encodedPrimaryKey}/{pathInRecord}?count=true
    Note:
    The field must be either an association node, a selection node, a terminal node or above.
    Where:
  • {category} corresponds to the operation category.
  • {dataspace} corresponds to B followed by the dataspace identifier or to V followed by the snapshot identifier.
  • {dataset} corresponds to the dataset identifier.
  • {pathInDataset} corresponds to the path of the dataset node, that can be a group node or a table node.
  • {encodedPrimaryKey} corresponds to the encoded representation of the primary key.
    See also:
  • {pathInRecord} corresponds to the path starting from the table node.

Parameters

The following parameters are applicable to the count operation.
Parameter Description
count This parameter is used to specify whether this is a count operation or a selection operation. Boolean type, default value is false.

Table parameters

The following parameters are applicable to tables, associations and selection nodes.
Parameter
Description
filter
XPath predicate expression defines the field values to which the request is applied. If empty, all records will be considered.
String type value.
Note:
The history code operation value is usable with the ebx-operationCode path field from the meta section associated with this field.
historyMode
Specifies the filter context applied on table.
String type, possible values are:
  • CurrentDataSpaceOnly: history in current dataspace
  • CurrentDataSpaceAndAncestors: history in current dataspace and ancestors
  • CurrentDataSpaceAndMergedChildren: history in current dataspace and merged children
  • AllDataSpaces: history in all dataspaces
The default value is CurrentDataSpaceOnly.
See also:
Note:
This parameter is ignored with the data category.
includeOcculting
Includes the records in occulting mode.
Boolean type, default value is false.
viewPublication
Specifies the name of the published view to be considered during the count execution. This parameter can be combined with:
  • the filter parameter as the logical and operation.
The behavior of this parameter is described in the section EBX® as a Web Component.

Selector parameters

The following parameters are only applicable to fields that return an enumeration, foreign key or osd:resource.
Parameter
Description
selector
Specifies whether:
  • true: returns the number of all possible values
  • false: returns the number of possible values for the current field.
Boolean type, default value is false.
Note:
This parameter is ignored with the history category.
selectorFilter
Specifies the filter of the selector.
String type value, the syntax complies with the Text search.

HTTP codes

HTTP code
Description
200 (OK)
The selected resource is successfully counted.
400 (Bad request)
The request is incorrect. This occurs when:
  • The selected field in a record or a dataset is sub-terminal.
  • The selected dataset field is a dataset tree.
  • The XPath predicate of the filter parameter is malformed or contains unfilterable nodes.
  • The table view for the viewPublication parameter is either hierarchical, non-existent or non-published.
  • The selector parameter is used for a non-enumerated node, or the firstElementIndex is negative, higher than or equal to the number of values.
403 (Forbidden)
The selected resource is hidden for the authenticated user.
404 (Not found)
The selected resource is not found.

Optimistic locking

To prevent an update or a delete operation on a record that was previously read but may have changed in the meantime, an optimistic locking mechanism is provided.
To enable optimistic locking, a select request must set the parameter includeTechnicals to true.
See Technical data for more information.
The value of the lastUpdateDate property must be included in the following update request. If the record has been changed since the specified time, the update or delete will be cancelled.
  • Record: update whole or partial content of the selected record.
    The property lastUpdateDate should be added to the request body to prevent update of a modified record.
    See the JSON example of a record.
  • Field: update of a single field of the selected record.
    The property value lastUpdateDate must be declared in the request URL by the checkNotChangedSinceLastUpdateDate parameter to prevent the update of a modified record.
The property value lastUpdateDate can also be used in the request URL checkNotChangedSinceLastUpdateDate parameter to prevent deletion on a modified record.
Note:
The checkNotChangedSinceLastUpdateDate parameter may be used more than once but only on the same record. This implies that if the request URL returns more than one record, the request will fail.

Inheritance

EBX® inheritance features are supported by built-in RESTful services using specific properties and automatic behaviors. In most cases, the inheritance state will be automatically computed by the server according to the record and field definition or content. Every action that modifies a record or a field may have an indirect impact on those states. In order to fully handle the inheritance life cycle, direct modifications of the state are allowed under certain conditions. Forbidden or incoherent explicit alteration attempts are ignored.
See also:

Record inheritance life cycle in built-in RESTful services

Inheritance properties

The following table describes properties related to the EBX® inheritance features.
Property
Location
Description
inheritance
record or table metadata
Specifies if dataset inheritance is activated for the table. The value is computed from the data model and cannot be modified through built-in RESTful services.
See also:
inheritedField
field metadata
Specifies the field's value source. The source data are directly taken from the data model and cannot be modified through built-in RESTful services.
See also:
inheritanceMode
record in child dataset
Specifies the record's inheritance state. To set a record's inheritance from overwrite to inherit, its inheritanceMode value must be explicitly provided in the request. In this specific case, the content property will be ignored if present. occult and root explicit values are always ignored. An overwrite explicit value without a content property is ignored.
Note:
Inherited record's fields are necessarily inherit.
Note:
Root records in child dataset will always be root.
Possible values are: root, inherit, overwrite, occult. For more information, see Record lookup mechanism.
field in overwrite record
Specifies the field's inheritance state. To set a field's inheritance to inherit, its inheritanceMode value must be explicitly provided in the request. The content property will be ignored in this case. overwrite explicit value without a content property is ignored.
Note:
inheritanceMode at field level does not appear for root, inherit and occult records.
Note:
inheritedFieldMode and inheritanceMode properties cannot be both set on the same field.
Possible values are: inherit, overwrite. For more information, see Inheritance and value resolution.
inheritedFieldMode
inherited field
Specifies the inherited field's inheritance state. To set a field's inheritance to inherit, its inheritedFieldMode value must be explicitly provided in the request. The content property will be ignored in this case. overwrite explicit values without a content property are ignored.
Note:
inheritedFieldMode and inheritanceMode properties cannot be both set on the same field.
Note:
inheritedFieldMode has priority over the inheritanceMode property.
Possible values are: inherit, overwrite. For more information, see Value lookup mechanism.

Limitations

General limitations

  • Indexes, in the request URL {pathInDataset} or {pathInRecord}, are not supported.
  • Nested aggregated lists are not supported.
  • Dataset nodes and field operations applied to nodes that are sub-terminal are not supported.
    See Access properties for more information about terminal nodes.

Read operations

  • Within the selector, the pagination context is limited to the nextPage property.
  • Within the viewPublication parameter, the hierarchical view is not supported.
  • The sortOnLabel parameter ignores programmatic labels.
  • The system information response's properties cannot be browsed through the REST URL with the hierarchical representation.
    See System information operation for more information.

Write operations

  • Association fields cannot be updated, therefore, the list of associated records cannot be modified directly.
  • Control policy onUserSubmit-checkModifiedValues of the user interface is not supported. To retrieve validation errors, invoke the select operation on the resource by including the includeValidation parameter.
    See Blocking and non-blocking constraints for more information.

Directory operations

  • Changing or resetting a password for a user is not supported.