The web socket API is used for real time collaboration. When a user makes a change, for example when creating a new database application, then the backend broadcasts a message containing that application to all the users within the related workspace and who are connected to the web socket. The web-frontend uses the web socket to update already fetched data in real time when it has changed. This ensures that the user is always working with the most recent data without reloading the page.
In order to connect to the web socket you first need to authenticate via the REST API
and obtain a JSON Web Token. After that you can connect to the
following URL providing your JWT as query parameter:
wss://api.baserow.io/ws/core/?jwt_token=YOUR_JWT_TOKEN
. If you self host
you need to replace api.baserow.io
with your own backend URL. The web socket
connection only receives messages targeted at the workspaces that the authenticated user
belongs to. Below is an example of how to connect to the web socket in JavaScript.
const socket = new WebSocket('wss://api.baserow.io/ws/core/?jwt_token=YOUR_JWT_TOKEN')
socket.onopen = () => {
console.log('The connection is made')
}
socket.onmessage = (message) => {
console.log('Received', message)
}
Broadcasted messages containing real time updates are always JSON, and they
always contain a key named type
which indicates what has changed. For example
create_application
could be the value of the type and in this case an additional key
application
is provided containing the newly created application in serialized form.
Below you will find an example of a message when another user has created a database application in a workspace that the receiver also belongs to. There are of course many event types, they are described at the bottom of this page.
{
"type": "application_created",
"application": {
"id": 123,
"name": "Test",
"order": 8,
"type": "database",
"workspace": {
"id": 1,
"name": "Bram's workspace"
},
"tables": []
}
}
After making the connection you will receive an authentication
message indicating if
the JWT token authentication was successful. If so, the message will also contain a
web_socket_id
. When making a change via the API, for example creating a new
application, you can provide that id as header WebSocketId: {YOUR_WEB_SOCKET_ID}
to
exclude yourself from the message containing the change that has already been executed.
Below you will find such an example authentication message including web_socket_id
and an example HTTP request containing the WebSocketId
header.
{
"type": "authentication",
"success": true,
"web_socket_id": "934254ab-0c87-4dbc-9d71-7eeab029296c"
}
PATCH /api/applications/1/
Host: api.baserow.io
Content-Type: application/json
WebSocketId: 934254ab-0c87-4dbc-9d71-7eeab029296c
{
"name": "Test",
}
A user will receive all the core messages related to workspaces and application by default, but we also have messages related to certain pages, for example to the table page. Because we don’t want to cause an overload of messages you can subscribe to a page of your interest. It is also possible to be subscribed to multiple pages. If successful you will receive messages related to that page. You will need to manually unsubscribe from a page to stop receiving updates.
Subscribing to a table page will request updates related to a Baserow table that will give you information about new rows, row updates, and other relevant information.
A table page expects thetable_id
parameter. Below you will find an example how to subscribe to that page.
{
"page": "table",
"table_id": 1
}
Once successfully subscribed you will receive a confirmation message indicating that you are subscribed to the page.
{
"type": "page_add",
"page": "table",
"parameters": {
"table_id": 1
}
}
Subscribing to a Row page will request additional updates related to a Baserow row of a particular table that will give you information like row history updates. Please note that to get updates such as row deletions and similar, you should use the table page described above.
A Row page expects thetable_id
and row_id
parameters. Below you will find an example how to subscribe to that page.
{
"page": "row",
"table_id": 1,
"row_id": 1
}
Once successfully subscribed you will receive a confirmation message indicating that you are subscribed to the page.
{
"type": "page_add",
"page": "row",
"parameters": {
"table_id": 1,
"row_id": 1
}
}
To stop receiving updates related to a page you are subscribed to, you will need to send a remove_page
message with the same page parameters that led to the subscription:
{
"remove_page": "row",
"table_id": 1,
"row_id": 1
}
authentication
page_add
page_discard
before_group_deleted
user_updated
user_deleted
user_restored
user_permanently_deleted
group_created
group_updated
group_deleted
group_restored
group_user_added
group_user_updated
group_user_deleted
application_created
application_updated
application_deleted
applications_reordered
table_created
table_updated
table_deleted
tables_re_ordered
field_created
field_updated
field_deleted
field_restored
rows_created
rows_updated
rows_deleted
before_rows_update
before_rows_delete
row_history_updated
view_created
view_updated
view_deleted
view_filter_created
view_filter_updated
view_filter_deleted
view_filter_group_created
view_filter_group_updated
view_filter_group_deleted
view_sort_created
view_sort_updated
view_sort_deleted
view_decoration_created
view_decoration_updated
view_decoration_deleted
view_field_options_updated
views_reordered
row_comment_created
row_comment_updated
row_comment_deleted