TIBCO EBX®
Documentation > Developer Guide > REST data services
Navigation modeDocumentation > 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:

Activation and configuration

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

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

Currently only the HTTP(S) protocol is supported.

Interactions

Input and output message encoding

All input and output messages must be exclusively in UTF-8 for REST built-in.

Tracking information

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

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.

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:

The filter behavior is described by this combinatorial:

Data services channel

XML element

Value

Schema node type

View

Behaviour

<hiddenInDataservices>truefield 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.

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. For example:

{
  "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

Security

Authentication

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

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.

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.

SOAP and REST comparative

Operations

SOAP

REST

Data

Select metadata

X

Select or count records (with filter and/or view publication)

X

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

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

Other

Develop web services from the Java API

X (*)

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

Documentation > Developer Guide > REST data services