Skip to main content

Map Storage API

Self Hosted
Available in WorkAdventure Self Hosted
 Free
Not available in WorkAdventure SaaS Free Plan
 Premium
Available in WorkAdventure SaaS Premium Plan

The Map Storage API is an HTTP REST API used by developers to create and update rooms stored in the WorkAdventure server.

WAM vs TMJ files, the 2 sides of WorkAdventure maps​

If you have already created a map for WorkAdventure, you already know that maps are designed in Tiled. Tiled produces TMJ files, which are JSON files that describe the map. Those files can be hosted on any web server.

You might also have noticed that WorkAdventure has an inline map editor. This editor allows you to add objets to the map such as tables, chairs... and also interactive areas.

Because the TMJ file can be hosted anywhere on the web, WorkAdventure does not have write access to the TMJ file. Therefore, the inline map editor cannot modify the TMJ file. Instead, the inline map editor edits WAM files.

There is one WAM file for each room of your world.

The WAM file is a JSON file that contains the list of objects and interactive areas. It also points to the TMJ file that should be used to render the map.

Those WAM files are stored (along other regular files) in the map-storage container. The map-storage API allows you to create, update and delete any file within that container.

So in order to create a new room for your users, you will just need to create a new WAM file in the map-storage container.

Getting the endpoint and the authentication token​

The map-storage API is protected by an authentication token. You can find this token, along the URL of the endpoint in the administration dashboard of WorkAdventure.

Connect to your dashboard, and go to Developers > API keys / Zapier.

If you do not already have an API key, click on "Create new token".

API Settings

Passing the authentication token to your request​

The Map Storage API is a REST API. Therefore, you need to pass the authentication token using the Authorization HTTP header, as a "Bearer" token (you need to prefix the token with the word "Bearer " in the Authorization HTTP header).

Sample query:

PUT /my_office.wam
Authorization: Bearer [your_token] 

{
    // WAM file content
}

Creating a new room​

To create a new room, you will use the PUT HTTP method on the map-storage API. The path of the request is the name of the WAM file you want to create.

For instance, if you want to create a new room called office/first_floor.wam, you will send a PUT request to the following URL:

PUT /office/first_floor.wam

Your map can then be accessed at the following URL:

https://play.workadventu.re/@/[organization_slug]/[world_slug]/office/first_floor.wam

If you are using a custom domain, the map URL will be:

https://[your_domain]/@/office/first_floor.wam

Minimal WAM file​

Here is a minimal WAM file:

{
    "version": "1.0.0",
    "mapUrl": "https://your_server/your_map.tmj",
    "entities": {},
    "areas": [],
    "entityCollections": [
        {
            "url": "https://play.workadventu.re/collections/FurnitureCollection.json",
            "type": "file"
        },
        {
            "url": "https://play.workadventu.re/collections/OfficeCollection.json",
            "type": "file"
        }
    ],
    "metadata": {
        "name": "The map name",
        "description": "A description displayed when sharing the map",
        "thumbnail": "https://your_server/thhumbnail.png",
        "copyright": "Credits: ..."
    }
}

The mapUrl property is the URL of the TMJ file that will be used to render the map.

The entityCollections property is the list of collections of objects that will be available in the inline map editor. You can learn more about the file format of those collections in the inline map editor documentation.

WAM file format​

If you are interested in the JSON schema of the WAM file, you can find it here: https://github.com/workadventure/workadventure/blob/master/docs/schema/1.0/wam.json

Reading a WAM file​

To read a WAM file, you will use the GET HTTP method on the map-storage API.

GET /office/first_floor.wam

Editing a WAM file​

You can modify special parts of a WAM file using the PATCH HTTP method.

The PATCH HTTP method expects a valid JSON Patch document as the body of the request.

PATCH /office/first_floor.wam
Content-Type: application/json-patch+json'
Authorization: Bearer [your_token] 

{
    "op": "add",
    "path": "/metadata/name",
    "value": "The new name of the map"
}

Deleting a WAM file​

You can delete a room using the DELETE HTTP method.

DELETE /office/first_floor.wam
Authorization: Bearer [your_token]

Storing other kind of files​

Although the map-storage API is primarily for WAM files, it can store various file types, including TMJ files, tilesets, and more. However, it's often easier to store these files on a regular web server, utilizing platforms like GitHub Pages or GitLab Pages for deployment.