Skip to main content

Room API

The Room API is a gRPC-based API that allows an external server to connect to a room and to perform actions such as reading/modifying/listening to a room variable.

The Room API is a server to server API. If you are looking for a "client to server" API (for instance to add a dynamic behavior to a map), look at the scripting API.

The Room API is not designed to create rooms or to manage members or authorizations on who can enter a room. If you are looking for an API to do this, look for the AdminAPI (in self-hosted mode) or the inbound or hooks if you are using the WorkAdventure SAAS version.

In WorkAdventure, the state of a room is stored in variables. You can bind those variables to some objects state (for instance to the fact that a door is closed or opened). Or you can use the scripting API to react to variables change.

The Room API lets you monitor those room variables, but also allows you to edit them. Through variables, you can therefore establish a 2-ways data channel between your server and what happens in a WorkAdventure room.

Protocol

You connect to the Room API using gRPC over HTTP2.

Why gRPC?

The Room API must be able to read and edit variables, but must also be able to listen in real-time to variables changes. The real-time aspect of the Room API makes a classic REST API not very well suited. We could have designed the API on Websockets or using Server-Sent Events, but those are hard to standardize.

The gRPC protocol provides an API that is self-documented (using .proto files), strictly typed, real-time and extremely performant.

Authentication

In order to connect to the Room API, you will need an authentication token.

You can issue a new authentication token in the administration dashboard of WorkAdventure.

  • Go to Settings > Developers
  • In the "Tokens" sections, click on "Create new token".
    API Settings
  • Give your token a name
  • Save the token for the next step.
    API Settings

Authentication to the API is done by passing a **X-API-Key** header in the gRPC metadata on each call to the API.

Endpoint

The Room API is available on the following endpoint:

HostnamePort
room-api.workadventu.re443

Client libraries

You want to contribute or create a new client ? Please check the existing clients before.

Protobuf file

The Protobuf file is available here.