Document instance_id field of /thirdparty/protocols

[zecakeh]

GET /_matrix/client/v3/thirdparty/protocols and GET /_matrix/client/v3/thirdparty/protocol/{protocol} currently return an undocumented field instance_id for each returned Protocol Instance.

The value of this field can be used as a parameter to POST /_matrix/client/v3/publicRooms.

instance_id has always been present since before the thirdparty protocol endpoints were added to the spec:

• Field added in Synapse in 2016: element-hq/synapse@2bf5a47
• Field added in matrix-react-sdk in 2018, it was imported from riot-web according to the commit message: matrix-org/matrix-react-sdk@8ab8f76
• It was however missing when the definitions of the thirdparty endpoints were added later in 2018: Thirdparty Entity Lookup API matrix-spec-proposals#1353 and Application service room directories (and other third party network things) matrix-spec-proposals#1554

I marked it as required because that is how it is defined in the TypeScript definition of the type in matrix-js-sdk, and according to the corresponding code in Synapse it is defined if network_id is defined, and according to the spec the latter is required. No longer marked as required: this would be a breaking change.

Fixes #833: The first paragraph of #833 seems to have been handled already, but this is about the second paragraph that is still relevant.

Pull Request Checklist

• Pull request includes a changelog file
• Pull request includes a sign off
• Pull request is classified as 'other changes'

Preview: https://pr2051--matrix-spec-previews.netlify.app

[richvdh]

thanks for looking into this!

[richvdh]

I'll take a closer look later, but I wanted to record:

I spoke to the SCT about this, and there was a suggestion that an interesting alternative would be to remove this feature from the spec altogether (i.e., at least remove third_party_instance_id from /publicRooms).

Element-Web does have support for instance_id/third_party_instance_id, but it doesn't seem to work very well. Particularly: GET /_matrix/client/v3/thirdparty/protocols does not, and has never worked, over federation; in addition, matrix.org now has very few bridges and it's unclear that the support is actually useful.

Obviously, such a change would require an MSC, along with research into whether any other parts of the protocol are also obsolete, so I'm not particularly suggesting anyone do that work immediately. But if anyone were interested in working in this area at any point, that would be nice.

[richvdh]

Thanks!