Metadata

The Metadata reference

Introduction

mitter.io allows attaching metadata to certain entities. Currently, Channels and Users are supported.

The examples below demonstrate operations with Channels, but the same can be performed on Users as well (by replacing "channels" in the URLs with "users", and providing the userId instead of the channelId)

Here is a sample API call to POST metadata:

POST /v1/channels/my-awesome-channel/metadata
{
    "type": "awesome-channel",
    "maxParticipants": 256,
    "meetingLocation": {
        "latitude": 12,
        "longitude": 12
    }
}

You can query Channels by metadata like so:

GET /v1/channels?metadata={type:"awesome-channel"}

NOTE: The URL in the example is not encoded for readability's sake, but it must be when making actual calls.

Behaviour

Metadata can be any valid JSON and adheres to the following rules:

1. The top level values of the JSON (in the above case, "awesome-channel", 256, and the location JSON) can only be string, numeric or JSON. It cannot be boolean.

2. Only top level keys can be used to query objects. For instance, in the above example, you can query Channels by type, maxParticipants and meetingLocation, but NOT by meetingLocation.latitude.

3. If you POST metadata with a key that already exists, it will be overridden. Keys with JSON values will not be merged.

4. When querying entities, you can specify multiple JSON, and all entities that match ALL queries will be fetched, i.e., if you provide multiple queries, the system will do an AND operation. For instance, if you execute GET /v1/channels?metadata={type: "awesome-channel", "age": 2}, then you will NOT get the above channel. Similarly, if you have two channels:

{
    "channelId": "channel-one",
    ...
    "metadata": {
        "type": "business",
        "area": "IN"
    }
}

{
    "channelId": "channel-two",
    ...
    "metadata": {
        "type": "business",
        "area": "EU"
    }
}

and you try to execute GET /v1/channels?metadata={type: "business"}, then the response will be channel-one