Search Results

TIBCO eFTL REST API Quick Start

Quick Start Contents

URL

The eFTL URL used with the REST API can be obtained from your TIBCO Cloud Messaging home page.

Note: You must use the URL scheme https with the REST API.

Security

TIBCO Cloud Messaging (TCM) can authenticate REST requests using either basic or token authentication. All REST requests are encrypted using HTTPS.

Basic Authentication

To use HTTP basic authentication use an authentication key from your TIBCO Cloud Messaging account as the password in the request. A username is not required. Authentication keys can be obtained from your TIBCO Cloud Messaging account page.

An example request using basic authentication

This basic authentication example supplies an authentication key as the password (using an empty username) with -u, and will print the HTTP response headers using -i.

curl -XPOST -i -u :{authentication-key} '{subscription-url}/v1/subscribe/quotes'

Token Authentication

Rather than sending your authentication key for each HTTP request, you have the option of extracting a token from a successful request using basic authentication, and using that token in subsequent requests.

Your clients must handle error response 401, unauthorized. This error could indicate an expired token. A client with an expired token can obtain a new token by sending another request with basic authentication.

For token authentication, extract the token from the HTTP response header X-Auth-Token of a successful request. The basic authentication example above uses the -i option to display the HTTP response headers.

An example request using token authentication

This token authentication example supplies a token as request header using -H. The token must be obtained from a previously successful basic authentication request.

curl -XPOST -H "X-Auth-Token: <x-auth-token>" '{subscription-url}/v1/subscribe/quotes'

Error JSON object

When an eFTL REST API request fails, the response will be a JSON object containing an error code, and reason. For example:

{
    "error": {
        "code": <code>,
        "reason": "<reason-string>"
    }
}

Creating a Durable Subscription

The HTTP method POST {subscription-url}/v1/subscribe/{durable_name} creates a durable subscription with the name durable_name. The variable subscription-url is the eFTL URL of your TCM account. The optional JSON request body specifies the content matcher to use. On success the response will be a JSON object containing the durable name and the content matcher definition. On failure the response will be an error JSON object.

HTTP query parameters for creating durables

Syntax Description
type=durable_type Optional. A durable type. Either standard, shared, or last-value. When absent, a standard durable is created.
key=key_field_name Required for last-value durables. Specify the key field of a last-value durable. The key field must be present in the subscription’s content matcher.

An example of creating a durable

The following curl example creates a last-value durable named orders, with the field named symbol as the key, and with {"symbol":"ibm"} as the content matcher:

curl -XPOST -u :{authentication-key} "{subscription-url}/v1/subscribe/orders?type=last-value&key=symbol" -d '{"symbol":"ibm"}'

{
  "durable": "orders",
  "matcher": {
    "symbol":"ibm"
  }
}

Publishing a message

The HTTP method POST {subscription-url}/v1/publish publishes a message. The variable subscription-url is the eFTL URL of your TCM account. The JSON request body is the message to publish. On success the response will be an empty JSON object {}. On failure the response will be an error JSON object.

An example of publishing a message

The following example publishes the JSON object {"symbol":"ibm", "price":120}:

curl -XPOST -u :{authentication-key} "{subscription-url}/v1/publish" -d '{"symbol":"ibm","price":120}'

{}

Publishing a message to key/value map

The HTTP method POST {subscription-url}/v1/kvmap/{map}/{key} publishes a JSON object (the value) to the key in the map specified. The variable subscription-url is the eFTL URL of your TCM account. On success the response will be an empty JSON object {}. On failure the response will be an error JSON object.

An example of publishing a message to a key/value map

The following example publishes the value {"price":120} to key ibm in the map named buys:

curl -XPOST -u :{authentication-key} "{subscription-url}/v1/kvmap/buys/ibm" -d '{"price":120}'

{}

Getting messages from a durable

The HTTP method GET {subscription-url}/v1/subscribe/{durable} gets zero or more messages from the specified durable. The variable subscription-url is the eFTL URL of your TCM account. On success the response will be a JSON object containing an array of messages. On failure the response will be an error JSON object.

One common usage pattern would be to repeat this request until the response array is empty, indicating that no messages remain in the durable subscription.

HTTP query parameters for getting messages

Syntax Description
timeout=wait_time Optional. When present, the request waits this interval (in seconds) for messages to become available. When absent or zero, the request returns immediately, even if no messages are available in the durable.
type=durable_type Required for shared and last-value durables. If a shared durable then type=shared. If a last-value durable then type=last-value.
key=field name Required for last-value durables. Specify the key field name.
matcher=json_content_matcher Required for last-value durables. Specify a content matcher that includes the key field of a last-value durable subscription.

An example of getting a message from a durable

The following curl example gets zero or more messages from the durable named orders. Because orders is a last-value durable the request query also includes the durable type, a key and a content matcher. The -g option is required to prevent curl from treating {} in the query string as special characters (see curl -h for more information).

curl -g -XGET -u :{authentication-key} '{subscription-url}/v1/subscribe/orders?type=last-value&key=symbol&matcher={"symbol":"ibm"}'

{
  "messages":[{
    "symbol": "ibm",
    "price": 120
  }]
}

Getting a message from a key/value map

The HTTP method GET {subscription-url}/v1/kvmap/{map}/{key} gets a JSON object (the value) from the key in the map specified. The variable subscription-url is the eFTL URL of your TCM account. On success the response will be a JSON object containing the value. On failure the response will be an error JSON object.

An example of getting a message from a key/value map

The following example gets a JSON object representing the value from the key ibm in the map named buys:

curl -XGET -u :{authentication-key} '{subscription-url}/v1/kvmap/buys/ibm'

{
  "value":{
    "price": 120
  }
}

Deleting a durable

The HTTP method DELETE {subscription-url}/v1/subscribe/{durable_name} deletes the durable subscription with the specified durable_name. The variable {subscription-url} is the eFTL URL of your TCM account. On success the response will be an empty JSON object {}. On failure the response will be an error JSON object.

An example of deleting a durable

The following curl example deletes the durable named orders:

curl -X DELETE -i -u :{authentication-key} '{subscription-url}/v1/subscribe/orders'

{}

Deleting a key from a map

The HTTP method DELETE {subscription-url}/v1/kvmap/{map}/{key} deletes the specified key from the map. The variable {subscription-url} is the eFTL URL of your TCM account. On success the response will be an empty JSON object {}. On failure the response will be an error JSON object.

An example of deleting a key from a map

The following curl example deletes the key ibm (and the value stored at the key) from the map buys:

curl -X DELETE -i -u :{authentication-key} '{subscription-url}/v1/kvmap/buys/ibm'

{}

Using curl on Microsoft Windows

The curl commands in this document may not work as intended on Windows. Try the following options if you have issues on Windows:

  • Use double quotes instead of single quotes.
  • Escape every double quote of your JSON payload, e.g. -d "{\"symbol\":\"ibm\", \"price\":120}"
  • Place the JSON payload in a file, e.g. payload.json, and reference the file using -d @payload.json.