Built-in RESTful services

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 for an intuitive and straightforward navigation, which implies that the data details could be obtained through a link.

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.

HTTP method

Considered HTTP methods for built-in RESTful services, are:

• GET: used to select master data defined in the URL (the size limit of the URL depends on the application server and on the browser; it must be lower than or equal to 2kB).

• POST: used to insert 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 by the table URL and the record keys 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 in the URL.

Operation category

Specializes the operation; it is added in the path of the URL in {category}, and takes one of the following values:

Header fields

These header field definitions are used by TIBCO EBX®.

See RFC2616 for more information about HTTP Header Field Definitions.

Common parameters

These optional parameters are available for all data service operations.

Message body

It contains the request data using the JSON format, see Extended JSON request body and Compact JSON request body.

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®.

HTTP codes

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 (Extended JSON and Compact 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.

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.

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 metamodel 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 metamodel 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'.

The URL format is:

http[s]://<host>[:<port>]/<ebx-dataservices>/rest/data/v1/Bebx-manager/ebx-manager/domain/toolStatus

Retrieve user interface state

User interface status and the unavailability message are accessible like dataset nodes.

See Select operation and the Extended JSON or Compact 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 Extended JSON or Compact 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

Parameters

The following parameter is applicable.

HTTP codes

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.

Create token operation

This operation requires using the POST HTTP method with a request containing the user's credentials and, optionally, session parameters.

The 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

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.

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

The 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

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.

The URL format is:

http[s]://<host>[:<port>]/<ebx-dataservices>/rest/auth/v1/token:revoke

Header fields

> Authorization: <tokenType> <accessToken>

HTTP codes

Data operations

The data category operations concern the datasets, the dataset fields, tables, records or record fields.

The data-compact category operations concern the dataset fields, tables, records or record fields.

The data-bo category operations concern data category operations with features to navigate through business objects.

The data-compact-bo category operations concern data-compact category operations with features to navigate through business objects.

The history category operations concern historized content from datasets, tables, records or record fields.

The form-data category operations concern the dataset fields, records or record fields when constraints must remain valid on content creation or update.

The form-data-compact category operations concern the dataset fields, records or record fields when constraints must remain valid on content creation or update.

See Form data operations for more information.

Select operation

Select operation returns hierarchical content. This operation may use one of the following methods:

• GET HTTP method,

• POST HTTP method without message body or

• POST HTTP method with a message body, with :select URL extended action and optionally session parameters.

URL formats are:

• Dataset tree, depending on operation category:

  The data, or data-compact, category returns the hierarchy of the selected dataset which includes group and table nodes.

  The history category returns the hierarchy of the selected history dataset which 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, or data-compact, category returns the terminal nodes contained in the selected node.

  http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}[:select]

  Note

  Not applicable with the history category.

• Table, depending on operation category:

  the data, or data-compact, category returns the table content and/or metamodel, current page records and URLs for pagination.

  The history category returns the history table content and/or metamodel, current page records and URLs for pagination.

  http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}[:select]

  See also

  • Count operation
  • Look up table views operation

• Record, depending on operation category:

  the data, or data-compact, category returns the record content and/or metamodel.

  The history category returns history record content and/or metamodel.

  http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}/{encodedPrimaryKey}[:select]

  http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}[:select]?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, or data-compact, 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}[:select]

  Note

  The field must be either an association node, a selection node, a terminal node or above.

Where:

• {category} corresponds to the operation category (possible values are: data, data-compact, data-bo, data-bo-compact or history).

• {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 percent encoded representation of the primary key (see RFC-3986 Uniform Resource Identifier ).

• {xpathExpression} corresponds to the record primary key, using the XPath expression.

• {pathInRecord} corresponds to the path starting from the table node.

• :select extended action is required when POST HTTP method is used with a body message.

Business object categories (data-bo and data-compact-bo) enrich the responses of Table, Record, and Field requests by adding data from other tables.

Parameters

The following parameters are applicable to the select operation.

Table parameters

The following parameters are applicable to tables, associations and selection nodes.

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 always enabled. Some selector's select operations require input values. Thus, the uses of POST HTTP method message body allows to provide a record content.

HTTP codes

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.

Examples: Extended JSON, Compact JSON.

Prepare operations

Prepare for creation or duplication operations are used to create a new transient record with an initial content or with the content of a record to duplicate. A transient record corresponds to a content that is not persisted yet. Default values and fields, initialized by table triggers, are considered. Only field values with, at least, read-only access permissions are returned. These operations can optionally return metamodel to improve and assist data capture on the client side. Auto-incremented fields are only returned in the metamodel. By enabling the selector parameter, a transient record's field can be queried to the retrieve possible values of an enumerated field, a foreign key, etc. Furthermore, selector's select operations allows to provide input record data to manage use cases like getting metamodel on a custom programmatic enumeration, etc.

After being modified on the client side, the record can be submitted to be persisted using the built-in Form insert operation or Insert operation operations.

These prepare operations may use one of the following methods:

• GET HTTP method,

• POST HTTP method without message body or

• POST HTTP method with a message body and optionally session parameters.

Available URL formats are:

• Prepare for creation

  • Record:

    http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}/{tablePath}:prepareForCreation

  • Record field:

    http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}/{tablePath}:prepareForCreation/{pathInRecord}

• Prepare for duplication

  • Record:

    http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}/{tablePath}/{encodedPrimaryKey}:prepareForDuplication

  • Record field:

    http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}/{tablePath}/{encodedPrimaryKey}:prepareForDuplication/{pathInRecord}

Where:

• {category} corresponds to the operation category (possible values are: data or data-compact).

• {dataspace} corresponds to B followed by the dataspace identifier.

• {dataset} corresponds to the dataset identifier.

• {tablePath} corresponds to the table path node.

• {encodedPrimaryKey} corresponds to the percent encoded representation of the primary key (see RFC-3986 Uniform Resource Identifier ).

• {pathInRecord} corresponds to the path starting from the table node.

Parameters

The following parameters are applicable to the prepare operations:

Selector parameters

The available parameters are similar to the selector operation ones.

HTTP codes

Response body

After a successful prepare for a creation or duplication request, the transient record is returned in the response body. The content depends on the provided parameters and selected data. However, it takes a format similar to the select operation record.

Examples: Extended JSON, Compact 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/{category}/v1/{dataspace}/{dataset}/{pathInDataset}[:mass]

Where:

• {category} corresponds to the operation category (possible values are: data or data-compact).

• {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.

• :mass extended action is required when updating a filtered set of records (see filter parameter).

Parameters

The following parameters are applicable with the insert operation.

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 Extended JSON, Compact JSON).

• Record table: Similar to the select operation on a table but without the pagination information (example Extended JSON, Compact JSON).

HTTP codes

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

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/{category}/v1/{dataspace}/{dataset}/{pathInDataset}

• Record: modifies the content of selected record.

  http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}/{encodedPrimaryKey}

  Note

  Also available for POST HTTP method. In this case, the URL must point to the table and the parameter updateOrInsert must be set to true.

  Note

  Use Insert operation with updateOrInsert=true and byDelta=true parameters to modify the content of several records.

• Field: update of a single field of the selected record.

  http[s]://<host>[:<port>]/<ebx-dataservices>/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}/{encodedPrimaryKey}/{pathInRecord}

  Note

  The field must be either a terminal node or above.

Where:

• {category} corresponds to the operation category (possible values are: data or data-compact).

• {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 percent encoded representation of the primary key (see RFC-3986 Uniform Resource Identifier ).

• {pathInRecord} corresponds to the path starting from the table node.

Parameters

Here are the parameters applicable with the update operation.

Message body

The request must define a message body.

The structure is the same as for:

• the dataset node (sample Extended JSON, Compact JSON),

• the record (sample Extended JSON, Compact JSON),

• the record fields (sample Extended JSON, Compact JSON),

depending on the updated scope, by only keeping the content entry.

HTTP codes

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}[:mass]

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 percent encoded representation of the primary key (see RFC-3986 Uniform Resource Identifier ).

• :mass extended action is required when deleting a filtered set of records (see filter parameter).

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.

Business object categories (data-bo and data-compact-bo) will do cascade deletion of all related records to the record to delete through business object relations.

Parameters

Here are the following parameters applicable with delete operation.

Message body

The request must define a message body only when deleting several records without using filter or deleteAll query parameter:

• 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

  • PrimaryKey

  Examples: Extended JSON, Compact JSON.

HTTP codes

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/{category}/v1/{dataspace}/{dataset}/{pathInDataset}:count

  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

• 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

  Note

  The field must be either an association node, a selection node, a terminal node or above.

Where:

• {category} corresponds to the operation category (possible values are: data or data-compact).

• {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 percent encoded representation of the primary key (see RFC-3986 Uniform Resource Identifier ).

• {pathInRecord} corresponds to the path starting from the table node.

Parameters

The following parameters are applicable to the count operation.

Table parameters

The following parameters are applicable to tables, associations and selection nodes.

Selector parameters

The following parameters are only applicable to fields that return an enumeration, foreign key or osd:resource.

HTTP codes

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 includeMetadata parameter including the system value.

See Technical data for more information.

The update_time property value must be included in the following request. If the record has been changed since the specified time, the update or delete operation will be cancelled.

• Record: update whole or partial content of the selected record.

  The update_time value 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 update_time value must be declared in the request URL by the checkNotChangedSinceLastUpdateTime parameter to prevent the update of a modified record.

The update_time property value can also be used in the request URL checkNotChangedSinceLastUpdateTime parameter to prevent deletion on a modified record.

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.

Record inheritance life cycle in built-in RESTful services

Inheritance properties

The following table describes properties related to the EBX® inheritance features.

Look up table views operation

The "look up published views" operation may use one of the following methods:

• GET HTTP method or

• POST HTTP method without message body.

The URL format is:

http[s]://<host>[:<port>]/<ebx-dataservices>/rest/data/v1/{dataspace}/{dataset}/{tablePath: [^:]*}:publishedViews

Where:

• {dataspace} corresponds to B followed by the dataspace identifier or to V followed by the image identifier.

• {dataset} corresponds to the dataset identifier.

• {tablePath: [^:]*} corresponds to the table path.

Parameters

No specific parameter for this operation.

Codes HTTP

Response body

It contains a collection of authorized view information (including the access URI).

Example: JSON.

Form data operations

The form-data category operations concern the dataset fields, records or record fields when creating or modifying content must comply with constraints on user form submit. They are intended to be used in a user form management context.

The request body of an operation is very similar to the equivalent operation of the data category in the sens that an incoming data validation feature and a result report has been added to the response. The data validation can not be deactivated, a parameter blockingConstraintsDisabled from the data category operations is not applicable. The validation phase fails when, at least, one constraint with a blocksCommit level set to onInsertUpdateOrDelete or onUserSubmit-checkModifiedValues is violated.

See Blocking and non-blocking constraints for more information.

Form insert operation

Insert form uses the POST HTTP method and requires a message body holding the data. This operation supports one or multiple records in a single transaction. Moreover, it is also possible to update record(s).

• Record: validate and insert a new record or modify an existing one in the selected table.

• Record table: validate and insert or modify one or more records in the selected table, while securing a consistent response. 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. The maximum number of records is limited to 100.

http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}[:mass]

Where:

• {category} corresponds to the operation category (possible values are: form-data or form-data-compact).

• {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.

• :mass extended action is required when updating a filtered set of records (see filter parameter).

Parameters

The following parameters are applicable with this insert operation.

Message body

The request must define a message body. The format is similar to the data category insert operation's message body.

HTTP codes

Response body

The response body will always hold a validation report. However in case of failure, the response body corresponds to a JSON Exception handling response.

• Record: The header field Location is returned with its URL resource. The validation report will be include in response body.

• Record table: (optional) Contains a list of validations report for each element, corresponding to the multiple validation report.

Form update operation

As for the data or data-compact category update operation, it allows the modification of a single dataset or record and the PUT HTTP method must be used. Available URL formats are:

• Dataset node: validates and modifies the values of terminal nodes contained in the selected node.

  http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}

• Record: validates and modifies the content of the selected record.

  http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}/{encodedPrimaryKey}

  Note

  Also available for POST HTTP method. In this case, the URL must point to the table and the parameter updateOrInsert must be set to true.

• Field: validates and update of a single field of the selected record.

  http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataset}/{encodedPrimaryKey}/{pathInRecord}

  Note

  The field must be either a terminal node or above.

Where:

• {category} corresponds to the operation category (possible values are: form-data or form-data-compact).

• {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 percent encoded representation of the primary key (see RFC-3986 Uniform Resource Identifier ).

• {pathInRecord} corresponds to the path starting from the table node.

Parameters

Here are the parameters applicable with the update operation.

Message body

The request must define a message body. The format is the same as for the data category update operation message body.

HTTP codes

Response body

The response body has the same format and behavior as the Form Insert operation.

Dataset operations

These operations perform selection over datasets.

Select datasets

Select operations can use the GET or POST methods.

URL formats are:

• Root: returns the root datasets of a given dataspace.

  A pagination mechanism is always enabled.

  http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}

• Children: returns the children datasets of a given dataset.

  A pagination mechanism is always enabled.

  http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}:children

• Information: returns dataset information.

  http[s]://<host>[:<port>]/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}:information

Where:

• {category} corresponds to the operation category (possible values are: data or data-compact).

• {dataspace} corresponds to B followed by the dataspace's identifier or to V followed by the snapshot's identifier.

• {dataset} corresponds to the dataset identifier.

Parameters

The following query parameters are applicable to Root and Children operations.

The following query parameters are applicable to Information operation.

HTTP codes

Response body

After a successful selection, the result is returned in the response body. The content depends on the provided parameters and selected data.

The format is linked to the selected object type:

• For Root and Children, see the extended JSON and compact JSON example.

• For Information, see the extended JSON and compact JSON example.

Dataspace operations

These operations perform a selection or life cycle management over dataspaces.

Beta feature: Select dataspaces or snapshots

Select operation may use one of the following methods: GET or POST. A pagination mechanism is always enabled.

URL formats are:

• Root: returns root dataspaces

  http[s]://<host>[:<port>]/ebx-dataservices/rest/data/v1/

• Children: returns children dataspaces of a given dataspace

  http[s]://<host>[:<port>]/ebx-dataservices/rest/data/v1/{dataspace}:children

• Snapshots: returns snapshots of a given dataspace

  http[s]://<host>[:<port>]/ebx-dataservices/rest/data/v1/{dataspace}:snapshots

• Information: returns a dataspace, or a snapshot, information

  http[s]://<host>[:<port>]/ebx-dataservices/rest/data/v1/{dataspace}:information

Where:

• {dataspace} corresponds to B followed by the dataspace's identifier or to V followed by the snapshot's identifier.

Parameters

The following query parameters are applicable to Root, Children and Snapshots operations.

HTTP codes

Response body

After a successful selection, the result is returned in the response body. The content depends on the provided parameters and selected data.

The format is linked to the selected object type:

• For Root, Children, or Snapshots, see the JSON example.

• For Information, see the JSON example.

Beta feature: Create a child dataspace or a snapshot

Creates the dataspace or snapshot as specified. This operation use the POST method with a body request (with no specific query parameter).

URL format are:

• Dataspace:

  http[s]://<host>[:<port>]/.../data/v1/{dataspace}:createDataspace

• Snapshot:

  http[s]://<host>[:<port>]/.../data/v1/{dataspace}:createSnapshot

Where:

• {dataspace} corresponds to B followed by the dataspace identifier.

Request body

The body specifies the features of the dataspace or the snapshot to create.

See the JSON example.

HTTP codes

Beta feature: Locking a dataspace

Locks the specified dataspace. If the dataspace is already locked:

• by the same user, then the lock is kept,

• by another user and during the wait duration, then the lock is acquired,

• otherwise, the lock is rejected.

This operation uses the POST method and consumes Content-Type header set to:

• application/x-www-form-urlencoded: with HTTP parameters in the body or

• application/json: with HTTP parameters in the URL and Session parameters into JSON body.

When it succeeds, no response body is returned.

The URL format is:

http[s]://<host>[:<port>]/.../data/v1/{dataspace}:lock

Where:

• {dataspace} corresponds to B followed by the dataspace identifier.

Parameters

The following query parameters are applicable to the operation.

HTTP codes

Beta feature: Unlocking a dataspace

Unlocks the specified dataspace. If the dataspace is:

• locked by the same user, then the lock is released,

• locked by another user, the current user is an administrator, and the forceByAdministrator query parameter is set to true, then the lock is released,

• not locked, the lock status is unchanged,

• otherwise, the unlock is rejected.

This operation uses the POST method and consumes Content-Type header set to:

• application/x-www-form-urlencoded: with HTTP parameters in the body or

• application/json: with HTTP parameters in the URL and Session parameters into JSON body.

When it succeeds, no response body is returned.

The URL format is:

http[s]://<host>[:<port>]/.../data/v1/{dataspace}:unlock

Where:

• {dataspace} corresponds to B followed by the dataspace identifier.

Parameters

The following query parameters are applicable to the operation.

HTTP codes

Beta feature: Merge a dataspace

Merges the specified dataspace to its parent. It is possible to perform deletion, after the merge, on history and / or on data.

This operation uses the POST method and consumes Content-Type header set to:

• application/x-www-form-urlencoded: with HTTP parameters in the body or

• application/json: with HTTP parameters in the URL and Session parameters into JSON body.

When it succeeds, no response body is returned.

The URL format is:

http[s]://<host>[:<port>]/.../data/v1/{dataspace}:merge

Where:

• {dataspace} corresponds to B followed by the dataspace identifier.

Parameters

The following query parameters are applicable to the operation.

HTTP codes

Beta feature: Close a dataspace or a snapshot

Closes the specified dataspace or snapshot. It is possible to perform deletion, after close, on history and / or on data.

This operation uses the POST method and consumes Content-Type header set to:

• application/x-www-form-urlencoded: with HTTP parameters in the body or

• application/json: with HTTP parameters in the URL and Session parameters into JSON body.

When it succeeds, no response body is returned.

The URL format is:

http[s]://<host>[:<port>]/.../data/v1/{dataspace}:close

Where:

• {dataspace} corresponds to B followed by the dataspace identifier or to V followed by the snapshot identifier.

Parameters

The following query parameters are applicable to the operation.

HTTP codes

Health operations

Overview

Operations health helps monitor the EBX® server.

Started operation

Returns status code 200 (Ok) when EBX® is started and initialized, otherwise it returns 503 (Service unavailable).

The URL format is:

http[s]://<host>[:<port>]/.../health/v1/started

HTTP codes

Response body

See the JSON example.

Check operation

Returns the status code 200 (Ok) when EBX® is started and checked, otherwise it returns 503 (Service unavailable).

The URL format is:

http[s]://<host>[:<port>]/.../health/v1/check

HTTP codes

Response body

See the JSON example.

Stopped operation

Returns the status code 200 (Ok) when the EBX® repository is shutdown, otherwise it returns 503 (Service unavailable).

The URL format is:

http[s]://<host>[:<port>]/.../health/v1/stopped

HTTP codes

Response body

See the JSON example.

OpenAPI operations

Overview

The api category operations comply with the OpenAPI specification 3.0.X to generate JSON documents. These documents facilitate development and consumption by structuring and describing the available REST built-in resources and the operations associated with them.

OpenAPI document HATEOAS links are available through the select data operations when using the includeOpenApiDetails query parameter.

The REST OpenAPI services permissions are globally defined in Global permissions.

Making the proper types mapping for generating a client, in a specific language, is essential. The OpenAPI format can be used to validate the input or to map the value to a specific type, in the chosen programming language. See Content of simple type for more information.

Generate OpenAPI documents

The operations use the GET or POST HTTP method to generate the OpenAPI document of a dataset, a table, or a schema node.

The URL formats are:

• Dataset:

  http[s]://<host>[:<port>]/ebx-dataservices/rest/api/v1/{category}/v1/{dataspace}/{dataset}

• Table and Schema node:

  http[s]://<host>[:<port>]/ebx-dataservices/rest/api/v1/{category}/v1/{dataspace}/{dataset}/{pathInDataset}

Where:

• {category} corresponds to an operation category among data, data-compact or form-data.

• {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:

  • a table node,

  • a dataset terminal node or above.

HTTP codes

Staging operations

The Staging REST API is designed to interact with source and target servers. It allows users to manage domains using export and import of staging archives.

The complete description of the services is available via OpenAPI on the following link:

http[s]://<host>[:<port>]/ebx-dataservices/rest/api/v1/staging/v1

In the development run mode, the Swagger UI is available on the following link.

http[s]://<host>[:<port>]/ebx-dataservices/rest/api/v1/staging/v1/ui

Domain management operations

The domains service allows the users to manage domains. The provided features are:

• Select the list of available domains.

• Select a domain by unique name.

• Create a new domain.

• Select the components of a domain.

• Add a component to a domain.

• Remove a component from a domain, the component is deleted.

Staging element navigation operations

The elements service is designed to display the whole elements of an instance in a hierarchical way. It is mainly designed for a UI interface that supports an hierarchical view with levels handling. The purpose of using query parameters instead of a structured body is to use links for easier navigation. The provided features are:

• Expands the content of an element.

• Expands the content of a specific type of elements under a selected element.

Archive manipulation operations

The archives service is designed for importing/exporting staging archives to/from a running instance in a single request. It is also used for uploading archives for asynchronous import. The provided features are:

• Export the archive of a domain.

• Import an archive to a running instance.

• Upload an archive for an asynchronous import.

The easiest way to export a staging archive via cURL

curl --request GET 'http[s]://<host>[:<port>]/ebx-dataservices/rest/staging/v1/archives/<domain>?login=<login>&password=<password>'

The easiest way to import a staging archive via cURL

curl --request POST 'http[s]://<host>[:<port>]/ebx-dataservices/rest/staging/v1/archives?login=<login>&password=<password>'
--header 'Content-Type: application/zip'
--data-binary '@/<archive-path-on-disk>'

Export operations

The exports service is designed to handle advanced export features. The archive is exported and stored on the server for a predefined period. The user can retrieve information about the archive, and it will be available to download it until it expires. The provided features are:

• Initiate an export.

• Get the status of an initiated export.

• Download an exported archive.

This endpoint can work in both synchronous and asynchronous modes.

Synchronous mode

A blocking mode that responds after exporting the whole archive on the server. The Archive will be immediately downloadable.

Asynchronous mode

A non-blocking mode that responds with an export ID and launches a task to export the archive. The client must poll the status endpoint to retrieve the status of the export. When the status changes to "Exported", the archive would be downloadable.

For consistency, any staging asynchronous job is aborted if it does not complete before 60 minutes of work.

Import operations

The imports service is designed to handle advanced import features. The archive is uploaded and stored on the server for a predefined period. The user can initiate an import asynchronously or retrieve information about an in-progress or completed import.

The archive is uploaded using the archives service with the option asyncImport=true.

The provided features are:

• Initiate an import by using an already uploaded archive.

• Get the status/report of an initiated import.

The archive name can be retrieved from an old import to initiate a re-import of the same archive with different options. It will be available until it expires.

This endpoint works only in asynchronous mode:

Limitations

General limitations

• Indexes, in the request URL {pathInDataset} or {pathInRecord}, 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.

Compact format limitations

• Inheritance, tracking information, session parameters and procedure context are not handled in the compact format. Use the extended one instead.

• History category is not supported in the compact format.

Business object category limitations

• In business object category: sort, filter, and history selection features can not be applied to a field under a relationship defined in a business object.

Read operations

• Within the selector, the pagination context is limited to the nextPage property.

• When the sortByRelevancy parameter is activated, the ones below are ignored: sort, sortOnLabel, sortPriority and sort criteria defined through the viewPublication.

• Within the viewPublication parameter, the hierarchical and tile views are 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.

• The prepare for creation operation does not support a dataset node.

• The select dataspaces operation does not sort them by label.

• The select snapshots operation does not sort them by creation date.

• The select snapshots operation can not include the initial snapshots.

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.

OpenAPI operations

• The document generation is not available through the user interface.

• The document generation REST services does not support the YAML format.

• Supports only Data operations and Form data operations except:

  • Select Dataset tree, Dataset node and Field operations.

  • Insert or delete multiple records in a single request.

  • Use of the HTTP header content-type: x-www-form-urlencoded to send query parameters in the body request.

• The 'Basic Authentication Scheme' is the only described method.