Cloud Software Group, Inc. EBX®
Documentation > Developer Guide > REST data services
Navigation mode Documentation > Developer Guide > REST data services

# Introduction

## Overview

REST data services allow external systems to interact with data governed in the TIBCO EBX® repository using the RESTful built-in services.

The request and response syntax for built-in services are described in the chapter Built-in RESTful services.

Built-in REST data services allow performing operations such as:

- Selecting, inserting, updating, deleting, or counting records

- Selecting or counting history records

- Selecting, updating, or counting dataset values

- Selecting or updating dataspace or snapshot information

- Selecting children dataspaces or snapshots

- Creating, merging, or closing a dataspace

- Creating or closing a snapshot

- Administrative operations to manage access to the UI or to system information

##### Note

See SOAP and REST comparative.

## Activation and configuration

REST and SOAP Data services are activated by deploying the `ebx-dataservices` web application along with the other EBX® modules. See Jakarta EE deployment for more information.

In case of specific deployment, for example using reverse-proxy mode, see URLs computing for more information.

Only HTTP(S) protocols are supported.

## Interactions

### Body media types

Input and output messages must be exclusively in JSON format with UTF-8 encoding for REST built-in. However, input message can also be used to pass HTML form data.

See Content-Type for more information.

### Tracking information

Depending on the data services operation being called, it may be possible to specify session-tracking information.

- Example for a RESTful operation, the extended JSON format request contains:

      {
      	"procedureContext":               // JSON Object (optional)
      	{
      		"trackingInformation": "String" // JSON String (optional)
      	},
      	...
      }

For more information, see `Session.getTrackingInfo` in the Java API.

### Session parameters

Depending on the data services operation being called, it is possible to specify session input parameters. They are defined in the request body.

Input parameters are available on custom Java components with a session object, such as: triggers, access rules, `custom` web services. They are also available on data workflow operations.

- Example for a RESTful operation, the extended JSON format request contains:

      {
      	"procedureContext":                // JSON Object (optional)
      	{
      		"trackingInformation": "String", // JSON String (optional)
      		"inputParameters":               // JSON Array (optional)
      		[
      			// JSON Object for each parameter
      			{
      				"name": "String",            // JSON String (required)
      				"value": "String"            // JSON String (optional)
      			},
      			...
      		]
      	},
      	...
      }

For more information, see `Session.getInputParameterValue` in the Java API.

### Session channel

The session channel allows to filter what can be selected or modified, from the EBX® repository, when using a REST built-in or REST toolkit service. The filter is based on table, group or field configuration where the visibility is defined through the data model, by specifying a default view.

It can be specified through the query parameter ebx-channel. It's available values are:

- `dataServices`

- `ui`

The filter behavior is described by this combinatorial:

#### Data services channel

XML element | Value | Schema node type | View | Behaviour
--- | --- | --- | --- | ---
`<hiddenInDataservices>` | `true` | `field node` | Default tabular view | Hidden for content and not sortable
CustomView (tabular or hierarchical) | Hidden for meta, content, filter and sort
Default form record | Hidden for meta and content
Default form record field | Not found

#### User Interface channel

XML element | Value | Schema node type | View | Behaviour
--- | --- | --- | --- | ---
<hidden> | true | table node | Tree view | hidden for meta and content
Default tabular view | not found
CustomView (tabular or hierarchical) | forbidden
Default form record | not found
Default form record field
Custom form record
field node | Default tabular view | hidden for content and not sortable
Default form record | hidden for content
Default form record field | not found
<hiddenInViews> | true | field node | CustomView (tabular or hierarchical) | hidden for meta, content, filter and sort
Custom form record | hidden for meta and content
<hiddenInSearch> | true | field node | Default tabular view | not filterable
CustomView (tabular or hierarchical)
Default form record
Default form record field
Custom form record
textSearchOnly | Default tabular view | not filterable except for text search
CustomView (tabular or hierarchical)
Default form record
Default form record field
Custom form record

##### Note

The above field nodes can only be under table nodes.

### Procedure context

Depending on the data services operation being called, it is possible to overwrite the default procedure context configuration. They are defined in the request body and are applied within the built-in operation.

Procedure context can be applied to custom REST Toolkit services.

- Example for a RESTful operation, the JSON request body contains:

      {
      	"procedureContext":            // JSON Object (optional)
      	{
      		"commitThreshold": Integer   // JSON Number (optional)
      	},
      	...
      }

For more information, see `ProcedureContext.setCommitThreshold`, `SessionContext.getProcedureUtility` and `ProcedureUtility.execute` in the Java API.

### Exception handling

When an error occurs, a JSON exception response is returned to the caller. In most cases the exception takes JSON format like in the REST Toolkit.

##### See also

- REST Toolkit exception handling

    {
      "code": 999,                      // JSON Number, HTTP error code or EBX® error code
                                        // in case of HTTP error 422 (optional)
      "errors": [                       // Additional messages to give details (optional).
        {
          "message": "Message 1"        // JSON String
        },
        {
          "message": "Message 2"
        }
      ]
    }

If there are errors when inserting or updating multiple records, an error report is returned.

    {
      "code": 999,               // JSON Number, HTTP status code
      "errors": [
        {
          "level": "...",        // JSON String, severity level (optional)
          "rowIndex": 999,       // JSON Number, request row index (optional)
          "userCode": "...",     // JSON String, user code (optional)
          "message": "...",      // JSON String, message
          "blocksCommit": "...", // JSON String, Type of blocking constraints (optional)
          "details": "...",      // JSON String, URL (optional)
          "pathInRecord": "...", // JSON String, Path in record (optional)
          "pathInDataset": "..." // JSON String, Path in dataset (optional)
        }
      ]
    }

The response contains an HTTP status code and a table of errors. The severity level of each error is specified by a character, with one of the possible values (`fatal`, `error`, `warning`, `info`).

The HTTP error `422` (Unprocessable entity) corresponds to a functional error. It contains a user code under the `userCode` key and is a JSON `String` type.

##### See also

- HTTP codes
- `Severity.getLabel`

## Security

### Authentication

Authentication is mandatory to access to the content. Several authentication methods are available and described below. The descriptions are ordered by priority (EBX® applies the highest priority authentication method first).

- 'Token Authentication Scheme' method is based on the HTTP-Header `Authorization`, as described in RFC 2617.

      > Authorization: <tokenType> <accessToken>

  For more information on this authentication scheme, see Token authentication operations.

  ##### See also

  - HTTP Authorization header policy

- 'Basic Authentication Scheme' method is based on the HTTP-Header `Authorization` in base64 encoding, as described in RFC 2617 (Basic Authentication Scheme).

      If the user agent wishes to send the userid "Alibaba" and password "open sesame",
      it will use the following header field:
      > Authorization: Basic QWxpYmFiYTpvcGVuIHNlc2FtZQ==

  ##### Note

  The `WWW-Authenticate` header can be valued with this method.

  ##### See also

  - HTTP Authorization header policy

- 'Bearer Authentication Scheme' method is similar to 'Token Authentication Scheme' but works with bearer tokens that may be issued from a third party provider.

      > Authorization: bearer <accessToken>

  For more information on this authentication scheme, see Bearer authentication configuration.

- 'Standard Authentication Scheme' is based on the HTTP `Request`. User and password are extracted from request parameters. For more information on request parameters, see Parameters section.

  For more information on this authentication scheme, see `Directory.authenticateUserFromLoginPassword`.

- The 'REST Forward Authentication Scheme' is used only when calling a REST service from a user service, that reuses the current authenticated session.

  For more information, see Implementing a user service making a call to REST data services.

- 'Specific authentication Scheme' is based on the HTTP `Request`. For example, an implementation can extract a password-digest or a ticket from the HTTP `Request`. See `Directory.authenticateUserFromHttpRequest` for more information.

- 'Anonymous authentication Scheme' is used only to access the REST services handling the authentication operations. The credentials acquisition, password changes, etc. implies that the user cannot be known yet.

### Global permissions

Global access permissions can be independently defined for the REST built-in and REST OpenAPI services. See Global permissions for more information.

### Lookup mechanism

Because EBX® offers several authentication methods, a lookup mechanism based on conditions was set to know which method should be applied for a given request. The method application conditions are evaluated according to the authentication scheme priority. If the conditions are not satisfied, the server evaluates the next method. The following table presents the available authentication methods for each supported protocol and their application conditions. They are ordered from the highest priority to the lowest.

Operation / Protocol | Authentication methods and application conditions
--- | ---
REST / HTTP | Token The HTTP request must hold an `Authorization` header. `Authorization` header value must start with the word `EBX`. No `login` is provided in the URL parameters. Basic The HTTP request must hold an `Authorization` header. `Authorization` header value must start with the word `Basic`. No `login` is provided in the URL parameters. Bearer Token The HTTP request must hold an `Authorization` header. `Authorization` header value must start with the word `Bearer`. No `login` is provided in the URL parameters. Standard The HTTP request must not hold an `Authorization` header. A `login` and a `password` are provided in the URL parameters. Rest forward The HTTP request must not contain an `Authorization` header. No `login` is provided in the URL parameters. Specific The HTTP request must not satisfy the conditions of the previous authentication methods. Anonymous None of the previous authentication methods can be applied. The requested REST service is handling an authentication operation.

In case of multiple authentication methods present in the same request, EBX® will return an HTTP code `401 Unauthorized`.

## Monitoring

Data service events can be monitored through the log category `ebx.dataServices`, as declared in the EBX® main configuration file. For example, `ebx.log4j.category.log.dataServices= INFO, ebxFile:dataservices`.

##### See also

- Configuring the EBX® logs
- TIBCO EBX® main configuration file

## SOAP and REST comparative

Operations | SOAP | REST
--- | --- | ---
Data |  |
Select metamodel |  | X
Select or count records (with filter and/or view publication) | X | X
Select records with association values (first level) | X |
Select business objects |  | X
Update or delete records (with filter and/or view publication) |  | X
Selector for possible enumeration values (with filter) |  | X
Prepare for creation or duplication |  | X
Insert, update or delete records | X | X
Select or count history records (with filter and/or view publication) |  | X
Select node values from dataset | X | X
Update node value from dataset |  | X
Get table or dataset changes between dataspaces or snapshots | X |
Refresh a replication unit | X |
Get credentials for records | X |
Generate service contract | WSDL | OpenAPI
Views |  |
Look up published table views |  | X
Datasets |  |
Select dataset information |  | X
Select root or child datasets |  | X
Dataspaces |  |
Select dataspace or snapshot information |  | X
Select root or children dataspaces, or select snapshots |  | X
Create, close, merge a dataspace | X | X
Create, close a snapshot | X | X
Validate a dataspace or a snapshot | X |
Validate a dataset | X |
Locking, unlocking a dataspace | X | X
Workflow |  |
Start, resume or end a workflow | X |
Administration |  |
Manage the default directory content 'Users', 'Roles'... tables. | X | X
Open, close the user interface | X | X
Select, insert, update, delete operations for administration dataset |  | X
Select the system information | X | X
Staging API |  | X
Health operations |  | X
Other |  |
Develop custom services from the Java API (*) |  | X
Generate custom service contracts (*) |  | OpenAPI

(*) See REST Toolkit for more information.

## Limitations

### Date, time & dateTime format

Data services only support the following date and time formats:

Type | Format | Example
--- | --- | ---
xs:date | yyyy-MM-dd | 2007-12-31
xs:time | HH:mm:ss or HH:mm:ss.SSS | 11:55:00
xs:dateTime | yyyy-MM-ddTHH:mm:ss or yyyy-MM-ddTHH:mm:ss.SSS | 2007-12-31T11:55:00

### JMS

- JMS protocol is not supported.

Documentation > Developer Guide > REST data services