Introducing REST APIs to build share dialogs, filterable overview pages, and a whole lot more

At Liveblocks, our mission is to empower companies and developers to create amazing document‑based collaborative products to enable people to feel more connected and work better together.

The first foundational step to accomplish this mission was about distributing tools and APIs that made it dead simple for developers to build multiplayer editor experiences. What do we mean by that? Think of the Figma’s, Notion’s, and Pitch’s of the world.

But outside of their collaborative editors, what do all those products also have in common? They have a great document/file browsing experience, a smooth share/invite flow driving organic product‑led growth, custom group/user permissions, and more!

Previous

Show slide 1Show slide 2Show slide 3Show slide 4Show slide 5Show slide 6

Next

Today, we’re excited to announce a new set of REST APIs that will help you build those critical experiences too. The possibilities are endless, but here are a few common collaborative UI patterns we’d like to highlight today:

• Share dialogs with permissions
• Filterable and paginated overview pages
• Groups with permissions

Share dialogs with permissions

The first major improvement is that rooms (or documents in this context) can have different permission types assigned at three different levels: default, groups, and users. We designed this solution to be easy-to-use, yet powerful and flexible, enabling companies to design and build permission systems that fit their unique requirements.

For instance, you can now easily add a world-class share dialog that will organically drive more people to your product.

To create the invitation system above, first we need to give a user a userId when authenticating, for example within authorize from @liveblocks/node.

import { authorize } from "@liveblocks/node";const response = await authorize({  userId: "ellen@acme.inc",  // ...});

Then we can use the update room API to assign permissions to that user.

const roomId = "my-room-name";fetch(`https://api.liveblocks.io/v2/rooms/${roomId}`, {  method: "POST",  body: JSON.stringify({    usersAccesses: {      "ellen@acme.inc": ["room:write"],    },  }),});

To check a user’s assigned permission types for this room, we can then use the get room API and check usersAccesses.

const roomId = "my-room-name";const url = `https://api.liveblocks.io/v2/rooms/${roomId}`;const response = await fetch(url);const room = await response.json();
// { "ellen@acme.inc": ["room:write"] }console.log(room.data.usersAccesses);

The invitation system can also be extended to groups of people too, for instance you could set permissions for the "engineering" group. To do this, first give users their groups when authenticating.

import { authorize } from "@liveblocks/node";const response = await authorize({  userId: "ellen@acme.inc",  groupIds: ["engineering"],  // ...});

Then, give the "engineering" group "room:read" and "room:presence:write" access to the document.

const roomId = "my-room-name";fetch(`https://api.liveblocks.io/v2/rooms/${roomId}`, {  method: "POST",  body: JSON.stringify({    groupsAccesses: {      engineering: ["room:read", "room:presence:write"],    },  }),});

The engineering group now has access to view the room, and to edit their presence (which can be used to display an online avatar).

To check if a user only has read-only access to storage in your app, the isReadOnly boolean can be also retrieved from others or self.

// Vanillaconst { isReadOnly } = room.getSelf();
// Reactconst selfIsReadOnly = useSelf((me) => me.isReadOnly);

Filterable and paginated overview pages

With this update, rooms can also have custom metadata associated with them, enabling you to build filterable and paginated overview pages.

For instance, if you have different document types in your product, it is now easy to expose those types as a filter—making it easy for people to find what they’re looking for.

One way to edit metadata is to use the create room API. In this example, we’re creating a new room with a custom type metadata, and setting it to "whiteboard".

fetch("https://api.liveblocks.io/v2/rooms", {  method: "POST",  body: JSON.stringify({    id: "room-id",    defaultAccesses: [],    metadata: {      type: "whiteboard",    },  }),});

We can then use get rooms API to retrieve a list of rooms containing the "whiteboard" type.

const metadata = "metadata.type=whiteboard";const url = `https://api.liveblocks.io/v2/rooms?${metadata}`;const response = await fetch(url);const rooms = await response.json();

And if you have hundreds of documents created, Liveblocks automatically takes care of pagination by returning the nextPage URL in the response—making it easy to fetch the next page by either clicking on a button or some sort of infinite scrolling behavior.

{  "nextPage": "/v2/rooms?startingAfter=W1siaWQiLCJVRzhWYl82SHRUS0NzXzFvci1HZHQiXSxbImNyZWF0ZWRBdCIsMTY2MDAwMDk4ODEzN11d",  "data": [    {      "type": "room",      "id": "room-id",      "lastConnectionAt": "2022-09-22T10:23:15.281Z",      "createdAt": "2022-09-22T10:23:15.281Z",      "metadata": {        "type": "whiteboard"      },      "defaultAccesses": ["room:write"]    }    // more rooms data would show here  ]}

Groups with permissions

With our new API endpoints, you can also create fully dedicated views for groups. Groups are a common pattern in seat-based collaborative products and are often used to organise documents for different teams and projects.

For instance, if you want to enable your users to configure groups, you could easily list them in side panel in your product overview page.

We’d then use the get rooms API to retrieve a list of rooms the group has access to.

const groupId = "engineering";const url = `https://api.liveblocks.io/v2/rooms?groupIds=${groupId}`;const response = await fetch(url);const rooms = await response.json();

Contributors

This month, we want to send a special shout-out to Vinod Santharam and Florent Lefebvre for their contribution. If you want to learn more about all the API endpoints we released, please check the API Reference. See you soon for the next update!