STOMP API

Iotellect Server supports STOMP API for integration with third-party software systems. You can use STOMP connections to subscribe and get notifications when desired context variables change or events occur.

Simple (or Streaming) Text Orientated Messaging Protocol (STOMP) is a text-based protocol, similar to HTTP. STOMP provides an interoperable wire format so that STOMP clients can communicate with any STOMP message broker to provide easy and widespread messaging interoperability among many languages, platforms and brokers.

The STOMP API does not support specifying additional headers for the client/browser when using the JavaScript WebSockets API. Take this limitation into consideration when designing applications.

For establishing connections, STOMP requests use the same URL and port number as the REST API.

Authenticating is performed via a REST API request.

To work with STOMP API as a client you will need to obtain an authentication token, create a client instance and then establish a connection between the client instance and the server using the token. All supported operations are performed after the connection between a STOMP client and a STOMP server has been established.

You can obtain the token by making an authentication request. Then connect your client instance to the server by passing it through a Connect request using the token.

Connects a STOMP client instance with a STOMP server. If no error occurs during the request's execution, the connection will be established as a result and you will obtain a representation of a STOMP session. Pass all other STOMP requests through this session.

The authentication token should be included into the request's headers. To obtain the token make an authentication request.

Request

/rest/v1/stomp

Request Header

Two options are available for authorizing STOMP requests:

1. Token based authentication, in which the following header is required:
   Authorization: {authentication_token}
   Replace {authentication_token} with the token received during authentication request.

2. Alternatively, using the login credentials for an Iotellect user, in which the following headers are required:
   login:{login}
passcode:{password}
   Replace {login} with the login of the user, and {password} password of the user.

Example Request

Request using localhost as a STOMP server's host and a default HTTP port number:

ws://localhost:8080/rest/v1/stomp

Request using localhost as a STOMP server's host and a default HTTPS port number:

ws://localhost:8443/rest/v1/stomp

Header:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJjOTQ1NTk0ZC01NGVmLTQ0ODItYWQxZi00NThhYWQwNzZlZDciLCJzdWIiOiJhZG1pbiIsImlhdCI6MTU5MDQ3OTQ2MywiZXhwIjoxNTkwNDgzMDYzfQ.AeaaXg7_m651JGquQ-WEzh_8Z7avL14s709dSd8wV4c

Subscribes to getting notifications when a variable value changes. As a result you will obtain a representation of the subscription. To unsubscribe from getting these notifications call a corresponding method of the subscription instance.

Request

/contexts/{context}/variables/{variable}

Replace {context} with a full context path.

Replace {variable} with a variable name.

Parameters

As a parameter, you should pass a handler for notifications. Every time the variable value changes, the handler will get the new value as incoming data.

Example

Subscribing to the info variable change of a context users.admin.devices.virtual:

/v1/contexts/users.admin.devices.virtual/variables/info

Example string representation of incoming data when the variable value changes:

[{"updateOriginator":0,"variable":"info","value":[{"localRoot":"","remotePath":"users.admin.devices.device1","icon":"st_device","remoteRoot":null,"mapped":false,"description":"Virtual Device 2","peerRoot":null,"type":"device.virtual","peerPrimaryRoot":null,"group":"default"}],"user":null}]

Subscribes to getting notifications when an event occurs. As a result you will obtain a representation of the subscription. To unsubscribe from getting these notifications call a corresponding method of the subscription instance.

Request

/v1/contexts/{context}/events/{event}

Replace {context} with a full context path.

Replace {event} with an event name.

Parameters

As a parameter, you should pass a handler for notifications. Every time the event occurs the handler will get the string representation of the event as incoming data.

Example

Subscribing to even1 of a context users.admin.devices.virtual:

/v1/contexts/users.admin.devices.virtual/events/event1

Example string representation of incoming data when the event occurs:

[{"date":"2000-02-01 12:00:00.000","string":"","int":0}]

Was this page helpful?

Tell us more

Send

Thank you!