WebSocket Gateway Service

Stream real-time information between your West Connectivity Solution and a web application

WebSocket endpoint scripts are developed within your application Endpoints tab in the same way as REST Http endpoints.

Each WebSocket connection and messages will trigger the execution of the deployed scripts.
Tips: the websocket upgrade endpoints support the same headers, query & path parameters capability as the Webservice service.

IMPORTANT: A single WebSocket connection has a limitation of 5 incoming messages per second.

Operations

Websocket.close() - Close a WebSocket connection
Websocket.closeAll() - Close all WebSocket connection
Websocket.info() - Get WebSocket
Websocket.list() - List WebSockets connections
Websocket.send() - Send a message to a WebSocket connection

Events

websocket_info - WebSocket request information

Operations

Please note that bold arguments are required, while italic arguments are optional.

close

Close a WebSocket connection and disconnect the client.
From a WebSocket endpoint script you can directly close the active connection by using websocketInfo.close() instead.
From any other script the service_ip and socket_id parameters are required.

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
socket_id	string	The WebSocket connection ID, provided in the websocket connection data websocketInfo .

Responses

Code	Body Type	Description
204	nil	Connection closed
default	object	Fail to close connection. More information available in the operation response.

Object Parameter of default response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Example

-- In a websocket Endpoint script: websocketInfo.close()

closeAll

Close all WebSocket connections for this solution.

Responses

Code	Body Type	Description
200	number	Number of connections closed
default	object	Fail to close connection. More information available in the operation response.

Object Parameter of default response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Example

local socket_count = Websocket.closeAll();

info

Get a WebSocket connection information. If the connection has been closed, an error will be returned.

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
socket_id	string	The WebSocket connection ID, provided in the websocket connection data websocketInfo .

Responses

Code	Body Type	Description
200	object	Websocket connection information
default	object	Fail to get active connections. More information available in the operation response.

Object Parameter of 200 response:

Name	Type	Description
uri	string(uri)	The full URI of WebSocket HTTP upgrade request
type	"open", "data", "close"	The state of WebSocket connection and type of event being triggered. From the WebSocket endpoint script, if the state == 'close' websocketInfo.send(..) and websocketInfo.close(..) functions are not usable.
route	string	The endpoint path, matching the custom API endpoint configuration
headers	object	The WebSocket HTTP upgrade request headers
message	string	The WebSocket message content
socket_id	string	Unique socket ID representing this websocket connection.
timestamp	integer	Message reception timestamp
parameters	object	The WebSocket HTTP upgrade request query parameters as a Map containing both from path and query parameters. Path parameters are defined in the endpoint path by using brackets. Eg. '/myendpoint/{pathParameterName}'. Query parameters are dynamically set from the url parameters following the format '/myendpoint?queryParameterNameOne=hello&queryParameterNameTwo=world'.
message_type	"data-text", "data-binary"	The WebSocket message type. 'data-binary' being based on a base64 encoding.

Object Parameter of default response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Example

local data = {
  ["socket_id"] = websocketInfo.socket_id
} local info = Websocket.info(data)

list

Retrieve the list of WebSocket connection IDs for this solution.

Responses

Code	Body Type	Description
200	[ string ]	A list of websocket connection IDs
default	object	Fail to get active connections. More information available in the operation response.

Object Parameter of 200 response:

Name	Type	Description

Object Parameter of default response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Example

local socket_ids = Websocket.list();

send

Send a message to a WebSocket connection by providing the destination socket_id.
The message field must be a string (Mind serializing Lua table with the to_json function).

When reply from a WebSocket event you can directly send messages to the active connection by using websocketInfo.send("message") instead.
In this case, if the given message is a lua table the value is automatically serialized into JSON string.

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
socket_id	string	The WebSocket connection ID, provided in the websocket connection data websocketInfo. Automatically set when calling websocketInfo.send("message") from West Connectivity endpoint script.
type	"data-text", "data-binary"	Data type used to transmit message to websocket client. 'data-binary' being based on a base64 encoding. Default: "data-text"
message	string	Content of the message

Responses

Code	Body Type	Description
204	nil	Message successfully sent
default	object	Fail to send message. More information available in the operation response.

Object Parameter of default response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Example

-- In a websocket Endpoint script:
websocketInfo.send("hello world")

Events

websocket_info

A WSS request has reached your custom API endpoint and triggers the websocket eventHandler script execution.
All requests trigger the same eventHandler script. However, for your convenience, West Connectivity provides out-of-the-box endpoint routing wrapper triggering endpoint scripts. So when writing an endpoint script, you simply can use the websocketInfo.send("message") or websocketInfo.close() functions.

However, if you want to set you own endpoint routing mechanism you can directly edit your solution webSocket websocket_info eventHandler script.

Important! Any endpoint script modification will reset the default routing mechanism and eventHandler script changes will be lost.

Arguments

websocketInfo (object) - WebSocket information

Name	Type	Description
uri	string(uri)	The full URI of WebSocket HTTP upgrade request
type	"open", "data", "close"	The state of WebSocket connection and type of event being triggered. From the WebSocket endpoint script, if the state == 'close' websocketInfo.send(..) and websocketInfo.close(..) functions are not usable.
route	string	The endpoint path, matching the custom API endpoint configuration
headers	object	The WebSocket HTTP upgrade request headers
message	string	The WebSocket message content
socket_id	string	Unique socket ID representing this websocket connection.
timestamp	integer	Message reception timestamp
parameters	object	The WebSocket HTTP upgrade request query parameters as a Map containing both from path and query parameters. Path parameters are defined in the endpoint path by using brackets. Eg. '/myendpoint/{pathParameterName}'. Query parameters are dynamically set from the url parameters following the format '/myendpoint?queryParameterNameOne=hello&queryParameterNameTwo=world'.
message_type	"data-text", "data-binary"	The WebSocket message type. 'data-binary' being based on a base64 encoding.

Example

-- In a WebSocket Endpoint script:
if (websocketInfo.type == "open") then



  -- Reply to the connection

  websocketInfo.send("Welcome")
elseif (websocketInfo.type == "data") then



  -- Print the incoming message and close the connection

  print(websocketInfo.message)
  websocketInfo.close()
end

-- Same behavior in EventHandler script:
function handle_websocket_websocket_info (websocketInfo)
  local responseData = {
    ["socket_id"] = websocketInfo.socket_id
  }
  if (websocketInfo.type == "open") then
    responseData.message = "Welcome"
    Websocket.send(responseData)
  elseif (websocketInfo.type == "data") then
    print(websocketInfo.message)
    Websocket.close(responseData)
  end
end

Service Health Check

Operations

/api/v1/solution/health

Enable the hosting system to check if service is active and running

Arguments

No Content

Responses

Name	Type	Description
200	string	OK

Errors

No content