Real-time data

RESTED_DEV 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.rested.dev/api/1/ce/examples/unsecure-endpoint?key=d59eb2859c284168ac48aef65046d5dd

Usage with websockets:

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

Usage example

function websocketExample() {
  console.log('Creating socket');
  let socket = new WebSocket(
    'wss://app.rested.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 httOnly, it is sent automatically with the request.

Request Cookies

Header	Description	Required
__Secure-rested-access-token	The 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.rested.dev/api/1/ce/examples/unsecure-endpoint?key=d59eb2859c284168ac48aef65046d5dd

Parameter	Description	Required
protocol	wss:// - Secure websocket over HTTPS.	Yes
baseUrl	Base url for calling the API. Value: app.rested.dev/api	Yes
versionNumber	Service version. Value: The current value is 1.	Yes
customEndpointRoute	The route which identifies custom endpoints. Default value: ce	Yes
userEndpoint	The endpoint name generated by the user. Value: the name created at https://app.rested.dev	Yes
apiKey	The API Key of the project.	Yes
accessToken	The access token received in the Authorization header after logging in. It should be sent without "Bearer ".	Yes - if the endpoint is secure and httpOnly cookie is not used.

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 code	Description
4000	Possible reasons: Endpoint or API Key not valid. No Access token or invalid. Origin not allowed.
1000	Possible reasons: Access token expired. Options of the endpoint are changed.

Successful response

If the connection is successful, when your endpoint receives new data or a record is modified, the connected client will receive the affected record in a 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.