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 to experience 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 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:

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 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 (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 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

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

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.

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

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.

URL format is:

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

Header fields

> Authorization: <tokenType> <accessToken>

HTTP codes

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

  • Count operation

• 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

  • RESTEncodingHelper

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

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

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.

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.

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

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/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

  • RESTEncodingHelper

• {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 JSON),

• the record (sample JSON),

• the record fields (sample 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}

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

  • RESTEncodingHelper

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.

Parameters

Here are the following parameters applicable with delete operation.

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

  • PrimaryKey

  Example 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/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

  • RESTEncodingHelper

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

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.

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.