Tibco

Using the REST APIs

This chapter describes how to use the public REST APIs.

Contents

REST Data Channels

REST data channels support accepting REST requests (source) from a REST client and generating REST responses (sink) as Server-Sent Events (SSE) to an SSE client. For more details about on how to configure and deploy a REST data channel, see the Working with Data Channels chapter.

Details on the public URL associated with a running REST Data Channel is in Public Addresses. A Swagger UI is available at the public URL.

Data Sink

When a REST data sink is running, it provides TIBCO REST Data Sink API.

The API generates an SSE event for each record processed by all connected pipelines. For yhe REST data sink, the schema of the SSE event is defined by the Schema Definition configured. The event is encoded in JSON by using a UTF-8 character encoding.

To access SSE events, perform the following calling sequence:

  1. POST /login - establish a login session
  2. GET /data - read SSE events
  3. POST /logout - terminate the login session

Data Source

When a REST data source is running, it provides TIBCO REST Data Source API.

The API provides an operation to generate an array of requests, which are transformed into records sent one at a time for processing to all connected pipelines.

A 500 response status failure is returned if there are no pipelines connected to the data source when a request is sent.

The format of the request is defined by the Schema Definition configured for the REST data source.

To generate requests for processing, perform the following calling sequence:

  1. POST /login - establish a login session
  2. POST /data - send one or more requests to all connected pipelines. Can be called multiple times without having to login again
  3. POST /logout - terminate the login session

REST Scoring Pipelines

When a scoring pipeline is exposed as a REST service, it provides TIBCO REST Pipeline API.

The API provides a POST /data operation to send and receive data from the associated pipeline.

The REST API is available as long as the scoring pipeline is running. When the scoring pipeline is shutdown, the associated REST API is also shutdown. A 404 response status failure is returned if connectivity is lost to the scoring pipeline.

Details on the public URL associated with a running REST Pipeline API is in Public Addresses. A Swagger UI is available at the public URL.

When a request is sent, the POST /data operation blocks waiting for the request are processed by the pipeline. When the processing is complete, the output is returned as the response to the POST /data operation.

The format of the request and response bodies in the POST /data API are defined by Input and Output processing steps in one of the scoring flows of the scoring pipeline. For more such details, see authoring flows.

The POST /data operation takes these optional query parameters:

Name Default Description
expectedResponseRecords 1 The expected number of response records before the API reports completion. This must be a value > 0.
waitTimeMilliseconds 1000 (ms) The maximum time the API blocks to wait for all response records. This must be a value > 0.

The query parameters control how many records must be accumulated before the POST /data operation completes, and how long it must wait for those records to be accumulated. If the waitTimeMilliseconds is exceeded before the number of expectedResponseRecords is received, the API returns success with the accumulated records (if any). Whether this is treated as an error or not is client specific and depends on one of the scoring flows running in the pipeline. For more such details on record aggregation in pipelines, see aggregation.

A request sent on the POST /data operation must contain a request identifier. The request identifier is used to perform request or response correlation as responses are received from a scoring pipeline. A response is associated with the request that contained the same request identifier. The application ensures that request identifiers are unique acrss all currently active requests that are sent to a scoring pipeline by all clients. Request identifiers are configured in the Unique Identifier Field.

The calling sequence to inject requests and receive responses from a scoring pipeline is:

  1. POST /login - establish a login session
  2. POST /data - send a request, and wait for a response, from a scoring pipeline. Can be called multiple times without having to login again.
  3. POST /logout - terminate the login session

Authentication

The REST APIs support these authentication schemes:

In both cases, a user’s credentials (username and password) are validated by the Kubernetes cluster Ingress, not the REST API. No credentials are maintained or enforced by the REST APIs. For more such details, see Security Architecture.

Supported Data Types

The REST data sink (in SSE events), data source (requests), and the REST pipeline API, support these data types:

OpenAPI Type OpenAPI Format Comments
boolean
integer int32 32 bit signed value
integer int64 64 bit signed value
number double Double precision floating point value
number float Single precision floating point value
string UTF 8 encoded character data
string Base64 encoded binary data (contentEncoding=base64)
string date RFC 3339 full-date
string date-time RFC 3339 date-time
array Supports all types in this table and can be nested
object Supports all types in this table and can be nested