Kafka WS
The Kafka WS service provides support for pure WebSocket connections to retrieve data directly from Kafka.
Ticket ¶
A ticket allows the user to subscribe to a dojot topic. To obtain it is necessary to have a JWT access token that is issued by the platform’s Authentication/Authorization service.
Getting a ticket ¶
A single-use TicketGET/kafka-ws/v1/ticket
Gets a single-use ticket. It can only be used once and has a very short validity period, it must be used to establish a websocket connection.
Example URI
Headers
Authorization: Bearer [Encoded JWT]
200
Headers
Content-Type: application/json
Body
{
"ticket": "ab1ee9ea52dec599bdc93259fae4539b7239a668ccf478cf52deba8c1cbef62f"
}
WebSocket ¶
The Kafka WS service allows the user to retrieve conditional and/or partial data from a topic in a Kafka cluster. It works with pure websocket connections, so you can create clients in any language you want, as long as the client supports RFC 6455 websockets.
For more details about grammar, selectors and conditions from this endpoint, check the
Kafka WS documentation under the subscription-engine/kafka-ws
directory in our
official repository.
NOTE THAT although it is specified as a GET endpoint, this is not an HTTP endpoint, but a
WebSocket one. To correctly use this endpoint, you must have some kind of WebSocket client. Check
the examples under the subscription-engine/kafka-ws
directory in our
official repository for ready to use Node.JS clients.
Retrieving conditional and/or partial messages from topic: ¶
Retrieve Kafka dataGET/kafka-ws/v1/topics/{topic}?ticket={ticket}&fields={selector}&where={conditions}
Example URI
- topic
string
(required) Example: topic.exampleThe
topic
parameter is the Kafka topic that you want to receive data from.- ticket
string
(required)Previously generated single-use ticket
- selector
string
(optional) Example: sensor/status,temperatureThe
fields
parameter tells Kafka WS to retrieve only determined parameters from the messages.- conditions
string
(optional) Example: sensor.status=in:failed,stopped;The
where
parameter tells Kafka WS to retrieve only messages in which the parameters meet the conditions.
Headers
Upgrade: WebSocket
Connection: Upgrade
200
Headers
Upgrade: WebSocket
Connection: Upgrade
Body
{
"sensor": {
"status": "failed"
},
"temperature": 35
}
426
Headers
Content-Type: text/plain
Body
Invalid request - non-WebSocket connection received in WS endpoint
4000
Websocket error
Body
INVALID_SYNTAX: there is a syntatic problem with `where`
4001
Websocket error
Body
INVALID_OPERATOR: an invalid operator has been passed to a condition
4002
Websocket error
Body
INVALID_ESCAPE_VALUE: an unsupported escape character has been passed to a condition
4003
Websocket error
Body
INVALID_OPERATOR_ARITY: the number of values in a condition is invalid for the operator
4004
Websocket error
Body
INVALID_VALUE: a value with an invalid type was passed to a condition
4403
Websocket error
Body
FORBIDDEN_TOPIC: the tenant sent in the token jwt cannot access the kafka topic passed
4408
Websocket error
Body
EXPIRED_CONNECTION: connection lifetime is over
4999
Websocket error
Body
INTERNAL: there is an error in the server