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 to perform operations such as:

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

• Selecting or counting history records

• Selecting, updating, or counting dataset values

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

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 protocol HTTP(S) 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.

• Example for a RESTful operation, the JSON 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 JSON 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.

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": [
  	{
  		"severity": "...",     // JSON String, severity (optional)
  		"rowIndex": 999,       // JSON Number, request row index (optional)
  		"userCode": "...",     // JSON String, user code (optional)
  		"message": "...",      // JSON String, message
  		"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 of each error is specified by a character, with one of the possible values (F: fatal, E: error, W: warning, I: information).

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.

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

• '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 base 64 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

• '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. imply that the user cannot be known yet.

Global permissions

Global access permissions can be independently defined for the REST built-in services access. For more information see Global permissions.

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.

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

(*) See REST Toolkit for more information.

Limitations

Date, time & dateTime format

Data services only support the following date and time formats:

JMS

• JMS protocol is not supported.