The original text wasn't far off, except for being wrong about what the fields actually do. This commit also adds a bit of clarity for how the server is expected to behave.
This intentionally doesn't document the third party network aspect of the endpoint. This is scheduled for a later area for dealing with third party network/IDs and is reported as https://github.com/matrix-org/matrix-doc/issues/1476
The client-server response has been broken out to a shared file: both the client-server and server-server /publicRoom endpoints return the same thing, with slightly different inputs.
The inputs (and behaviour) are based upon the docstring here: 43ecfe0b10/synapse/federation/transport/server.py (L583-L612)
This also adds a previously-undocumented endpoint: /state_ids
Backfill is technically not part of this section, however it is being left untouched to make the merge with #1469 easier (which moves it out of the file).
Reference material:
* Some calls to synapse on these endpoints with a relatively simple private room.
The response is based upon various sections of the Synapse code in how it generates a response.
There are no new fields added to the transaction. Originally, `previous_ids` and `pdu_failures` were to be documented however neither of these are used in the real world.
There isn't a whole lot to this section that needed work. The section overall lost the table schema in favour of having the endpoints close by.
The directory query is improved in https://github.com/matrix-org/matrix-doc/pull/1443
Most of the text has been shuffled into the swagger definitions to bring it closer to where it matters.
This also attempts to clarify what is out in the wild. Most importantly, the first version of the key exchange is outright removed from the specification. Other research points/questions are:
* What is a "Key ID"?
* 1241156c82/synapse/rest/key/v2/local_key_resource.py (L81-L83)
* 1241156c82/synapse/rest/key/v2/local_key_resource.py (L88-L91)
* Returning a cached response if the server throws a 400, 500, or otherwise not-offline status code
* 1241156c82/synapse/rest/key/v2/remote_key_resource.py (L227-L229)
* `minimum_valid_until_ts` default
* This branch of the ladder: 1241156c82/synapse/rest/key/v2/remote_key_resource.py (L192)
* Returning empty arrays when querying offline/no servers
* Queried by hand against matrix.org as a notary server with a fake domain name to query
* Returning all keys even when querying for specific keys
* Queried by hand using matrix.org as a notary server against a server publishing multiple keys.
The examples and descriptions were also improved as part of this commit.
This is a mix of Synapse and Dendrite behaviour, mostly Dendrite. Synapse returns `null` for field values that aren't set, however Dendrite just doesn't return them and instead opts for an empty object.
Further, synapse is lacking in error codes in this area. Dendrite does some additional validation on this API which introduces more errors for bad requests, instead of defaulting to empty objects/200 OK responses.
Likewise, Dendrite returns a 404 when the user is not found while Synapse returns 200 OK/empty object.
