Search Results

TIBCO eFTL™ REST API Quick Start

Contents

Connecting to TIBCO Cloud Messaging

The client configuration file contains all the information client applications need to securely connect to TIBCO Cloud Messaging. Generate the client configuration file using the roles REST API or user interface. Generate as many configuration files as needed for each Role.

cURL example

curl -XPOST -i -u {tcm_authentication_id}:{tcm_authentication_key} '{eftl_url}/v1/subscribe/quotes'

The tcm_authentication_id, tcm_authentication_key and eftl_url can all be found in the client configuration file.

Note: In order to connect using the REST API, you must replace the wss scheme in the eftl_url with https.

Error Responses

When an eFTL REST API request fails, the response is a JSON object containing an error code, and reason:

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

Creating a Durable Subscription

The HTTP method POST {eftl_url}/v1/subscribe/{durable_name} creates a durable subscription with the name durable_name. The variable eftl_url is the eFTL URL found in the configuration file with wss replaced with https. 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 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 {tcm_authentication_id}:{tcm_authentication_key} "{eft_url}/v1/subscribe/orders?type=last-value&key=symbol" -d '{"symbol":"ibm"}'

Result:

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

Publishing a message

The HTTP method POST {eftl_url}/v1/publish publishes a message. The variable eftl_url is the eFTL URL found in the configuration file with wss replaced with https. 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 {tcm_authentication_id}:{tcm_authentication_key} "{eft_url}/v1/publish" -d '{"symbol":"ibm","price":120}'

Result:

{}

Publishing a message to key/value map

The HTTP method POST {eftl_url}/v1/kvmap/{map}/{key} publishes a JSON object (the value) to the key in the map specified. The variable eftl_url is the eFTL URL found in the configuration file with wss replaced with https. 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 {tcm_authentication_id}:{tcm_authentication_key} "{eft_url}/v1/kvmap/buys/ibm" -d '{"price":120}'

Result:

{}

Getting messages from a durable

The HTTP method GET {eftl_url}/v1/subscribe/{durable} gets zero or more messages from the specified durable. The variable eftl_url is the eFTL URL found in the configuration file with wss replaced with https. 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 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 {tcm_authentication_id}:{tcm_authentication_key} '{eftl_url}/v1/subscribe/orders?type=last-value&key=symbol&matcher={"symbol":"ibm"}'

Result:

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

Getting a message from a key/value map

The HTTP method GET {eftl_url}/v1/kvmap/{map}/{key} gets a JSON object (the value) from the key in the map specified. The variable eftl_url is the eFTL URL found in the configuration file with wss replaced with https. 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 {tcm_authentication_id}:{tcm_authentication_key} '{eftl_url}/v1/kvmap/buys/ibm'

Result:

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

Deleting a durable

The HTTP method DELETE {eftl_url}/v1/subscribe/{durable_name} deletes the durable subscription with the specified durable_name. The variable eftl_url is the eFTL URL found in the configuration file with wss replaced with https. 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 example deletes the durable named orders:

curl -X DELETE -i -u {tcm_authentication_id}:{tcm_authentication_key} '{eftl_url}/v1/subscribe/orders'

Result:

{}

Deleting a key from a map

The HTTP method DELETE {eftl_url}/v1/kvmap/{map}/{key} deletes the specified key from the map. The variable eftl_url is the eFTL URL found in the configuration file with wss replaced with https. 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 example deletes the key ibm (and the value stored at the key) from the map buys:

curl -X DELETE -i -u {tcm_authentication_id}:{tcm_authentication_key} '{eftl_url}/v1/kvmap/buys/ibm'

Result:

{}

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: -d "{\"symbol\":\"ibm\", \"price\":120}"
  • Place the JSON payload in a file, and reference the file using -d @<filename>.