Real-time data

YAWE allows you to listen to changes on your endpoints using websockets.

To do this, you use the same endpoint created under projects, using the protocol wss instead of https.

Example#

Your endpoint:

https://app.yawe.dev/api/1/ce/examples/unsecure-endpoint?key=d59eb2859c284168ac48aef65046d5dd

Usage with websockets:

wss://app.yawe.dev/api/1/ce/examples/unsecure-endpoint?key=d59eb2859c284168ac48aef65046d5dd

Usage example#

function websocketExample() {
console.log('Creating socket');
let socket = new WebSocket(
'wss://app.yawe.dev/api/1/ce/examples/unsecure-endpoint?key=d59eb2859c284168ac48aef65046d5dd'
);
socket.onopen = () => {
console.log('Socket open.');
};
socket.onmessage = (message) => {
const data = JSON.parse(message.data);
console.log('Socket server message', data);
};
socket.onerror = (error) => {
console.error('Error ', error);
};
socket.onclose = (error) => {
console.error('Close ', error);
};
}

Connection#

When opening a connection to a websocket, the parameters of the URL are validated like we do for HTTP requests, such as, endpoint name, key, origin, data access and authentication. If any of the checks fail, the connection fails and an error is sent to the user.

If the endpoint is secure, your user needs to be logged in first. As the cookie with the access token is HTTP-only, it is sent automatically with the request.

Request Cookies#

HeaderDescriptionRequired
yawe_access_tokenThe Access token is required for secure endpoints.

It is set when login in and is automatically sent in the websocket request.

For more information check Secure Endpoints.

No

Request Parameters#

The following table describes the Request parameters to open a connection. Parameters not listed below are ignored.

URL example: wss://app.yawe.dev/api/1/ce/examples/unsecure-endpoint?key=d59eb2859c284168ac48aef65046d5dd

ParameterDescriptionRequired
protocol

wss:// - Secure websocket over HTTPS.

Yes
baseUrlBase url for calling the API.

Value: app.yawe.dev/api

Yes
versionNumberService version.

Value: The current value is 1.

Yes
customEndpointRouteThe route which identifies custom endpoints.

Default value: ce

Yes
userEndpointThe endpoint name generated by the user.

Value: the name created at https://app.yawe.dev

Yes
apiKeyThe API Key of the project.Yes

Response data / messages#

Error codes#

The connection to the websocket can fail or be terminated due to one of the reasons listed in the table below. You will be able to read the error message in the reason property of the error message.

Error codeDescription
4000Possible reasons:
  • Endpoint or API Key not valid.
  • No Access token or invalid.
  • Origin not allowed.
1000Possible reasons:
  • Access token expired.
  • Options of the endpoint are changed.

Successful response#

If the connection is successful, when there's new data in the endpoint or an update you will receive the affect record in the websocket message. Below is an example of such message:

/*
data(received as a string):
data: "{"type":"POST","record":{"data":{"someNewData":"test"},"uniqueId":"3cc236ed09ef4768ba1fe6dcaf43edea","updatedAt":"2021-06-28T17:18:44.000Z","createdAt":"2021-06-28T17:18:44.000Z"}}"
*/
{
record: {
createdAt: "2021-06-28T17:18:44.000Z",
data: {
someNewData: "test"
},
uniqueId: "3cc236ed09ef4768ba1fe6dcaf43edea",
updatedAt: "2021-06-28T17:18:44.000Z",
},
type: "POST"
}

Note: For files, if there are multiple uploads you will receive an array of records in the message.