matrix-spec/proposals/1337-improve-membership.md

Improving the way membership lists are queried

Problem scope

A common operation for bots, bridges, scripts, and clients is to determine what rooms the user is a member of and who the members of those rooms are. Although possible with the current specification, the API can be improved to provide more granular and simplified access to this information.

The affected routes are:

• GET /_matrix/client/r0/rooms/{roomId}/members
• GET /_matrix/client/r0/rooms/{roomId}/joined_members
• GET /_matrix/client/r0/joined_rooms

This proposal aims to resolve matrix-doc#1123.

Background

The /joined_members and /joined_rooms endpoints were originally added in synapse#1680 during a time when the IRC bridge on matrix.org was under extreme load. The endpoints were fully intended to alleviate load by having the bridge do less work and have the server doing more.

Proposal

This proposal calls for both /joined_members and /joined_rooms to be deprecated. The deprecation is to be coupled with improving how /members works and introducing a new /rooms endpoint, which will work in a very similar way to the updated /members endpoint. Both endpoints are proposed to get some way to filter based upon membership, as outlined in the options below.

Option 1: Query string

A new query parameter, membership, should be added to the /members endpoint. The parameter filters the membership list of the room such that only members with a matching membership are returned. The parameter can be supplied multiple times to filter on multiple membership states. For example, the request could be /members?membership=join&membership=invite to get all invited and joined members for the room. If no membership parameter is specified, the default is to return all members of the room regardless of membership state.

To compliment the /members endpoint, a new endpoint should be added to query the rooms for the user. This uses the same style of using a membership query parameter to filter the rooms.

Some examples of using this endpoint are below. The rooms field is an object where the key is a room ID and the value is information about that room, currently storing a single membership field. The value is an object to support future expansion of this API.

// GET /_matrix/client/r0/rooms?membership=join&membership=invite
{
   "rooms": {
       "!somewhere:domain.com": {
           "membership": "join"
       },
       "!elsewhere:matrix.org": {
           "membership": "invite"
       }
   }
}

// GET /_matrix/client/r0/rooms?membership=ban
{
   "rooms": {
       "!plzno:domain.com": {
           "membership": "ban"
       }
   }
}

// GET /_matrix/client/r0/rooms
{
   "rooms": {
       "!somewhere:domain.com": {
           "membership": "join"
       },
       "!elsewhere:matrix.org": {
           "membership": "invite"
       },
       "!plzno:domain.com": {
           "membership": "ban"
       },
       "!curbaf:domain.com": {
           "membership": "leave"
       }
   }
}

Option 2: Filter

As with Option 1, a new endpoint would be added to handle getting the list of rooms. However, instead of both /members and /rooms taking a query parameter for membership they would instead take a filter (re-using existing matrix concepts). Similar to how /messages works, this filter would be a RoomEventFilter instead of having all the available options. Additionally, the filter would support a membership field to filter based upon membership.

An example filter for getting members/rooms of membership invite or join would be:

{
   "limit": 5, // The maximum number of items to return. Defaults to no limit.

   // These only apply when fetching members in a room
   "senders": ["*"],
   "not_senders": [],

   // These only apply when fetching rooms
   "rooms": ["*"],
   "not_rooms": [],

   // NEW! Filter based upon the given membership values.
   "membership": ["join", "invite"],

   // These are copied from the RoomEventFilter schema, but are ignored
   "types": [],
   "not_types": [],
   "contains_url": true,
}

Option 3: Even more filters

Expanding on Option 2, we give /state the option of a filter (also from Option 2). This would require the types to be useful, and we could potentially deprecate the /members endpoint entirely with this approach.

Likewise, /context should take a similar filter so clients can get members at a given point in history.

Alternative solutions

Using ?membership=join,invite or ?membership=join+invite instead

The arguments in favour of this approach are:

• It doesn’t rely on undefined behaviour in RFC3986
• Using multiple keys in the query string hasn’t been done before in the matrix spec

The arguments against this approach are:

• It’s not as pretty and may require hex encoding
• It adds unnecessary complexity given most query string parsers are capable of handling multiple keys in the query string. It is additional complexity because implementations would now need to do string splitting instead of relying on their already-in-use parsing libraries

Encoding ?membership as a JSON value

The arguments in favour of this approach are:

• The filtering API already does this
• It doesn’t rely on undefined behaviour in RFC3986

The arguments against this approach are:

• It’s not as pretty and requires hex encoding
• Implementations would be forced to perform decoding, adding additional complexity (see the con for comma-separated values)