Investigate if there are unspecced endpoints that can be removed

[clokep]

We should investigate whether there are any unspecced (and unused) endpoints in Synapse.

See #8177 about some of the admin APIs being exposed under /_matrix/client.

I took a look at some of the federation APIs and client APIs also, will put some results in here tomorrow.

#8154 also has some related info.

[clokep]

I collated a bunch of this on a spreadsheet, but a summary is below.

Federation

Unspecced

• The various groups endpoints (under /_matrix/federation/v1/groups/), but are to be replaced (I believe).
• A room complexity endpoint (/_matrix/federation/unstable/rooms/{roomId}/complexity) was added in Implement the SHHS complexity API #5216.

Errors

• /_matrix/federation/v1/3pid/onbind (implemented by On3pidBindServlet) accepts POST, while the specification says it should accept PUT.

Client

Prefix

• All endpoints appear under /_matrix/client/unstable/, which is probably OK.
• Most endpoints appear under /_matrix/client/r0/, unless they're unstable endpoints.
• Some endpoints appear under /_matrix/client/api/v1/.

Unspecced

• The various groups endpoints (under /_matrix/client/(unstable|r0)/groups/, /_matrix/client/(unstable|r0)/create_group, under /_matrix/client/(unstable|r0)/publicised_groups, and /_matrix/client/(unstable|r0)/joined_groups), but are to be replaced (I believe).
• /_matrix/client/(unstable|api/v1|r0)/pushers/remove (implemented by PushersRemoveRestServlet).
• Listing appservices (/_matrix/client/(unstable|api/v1|r0)/directory/list/appservice/{networkId}/{roomId}), added in Extended protocol for content co-creation, beyond chat rooms matrix-spec#379. See Synapse supports unspecced DELETE /directory/list/appservice/<network ID>/<room ID> endpoint #14178
• Token refresh (/_matrix/client/(unstable|r0)/tokenrefresh), this endpoint simply raises an error, it can probably be deleted.
• Account validity (under /_matrix/client/(unstable|r0)/account_validity/), added in Add time-based account expiration #5027 and Send out emails with links to extend an account's validity period #5047.

Obsolete MSCs

Endpoints from MSCs which are obsolete (not accepted into the specification). Hopefully these can be removed.

• Relations and aggregations (under /_matrix/client/unstable/rooms/{roomId}/relations/, /_matrix/client/unstable/rooms/{roomId}/aggregations/, and /_matrix/client/unstable/rooms/{roomId}/send_relation/) from MSC1849: Proposal for m.relates_to aggregations matrix-spec-proposals#1849.
• Room keys (under /_matrix/client/(unstable|r0)/room_keys/) from MSC1687: Encrypting recovery keys for online megolm backups matrix-spec-proposals#1687.

Proposed MSCs

Endpoints for MSCs which are proposals and not yet accepted into the specification. Generally these are fine as is.

• /_matrix/client/(unstable|r0)/password_policy from MSC2000: Server-side password policies matrix-spec-proposals#2000 -- this should only be appearing under unstable, but also appears under r0.
• /_matrix/client/unstable/uk.half-shot.msc2666/user/shared_rooms/{userId} from MSC2666: Get rooms in common with another user matrix-spec-proposals#2666. (This seems fine.)

Merged MSCs

Endpoints for MSCs which were merged, but are not yet part of the specification. These should be unstable only.

• /_matrix/client/(unstable|r0)/keys/signatures/upload (implemented by SignaturesUploadServlet) from MSC1756: cross-signing devices using a master identity key matrix-spec-proposals#1756.

Implementation specific

Some endpoints aren't specced and are implementation specific (i.e. there are sent to the client as a redirect or sent to confirm email addresses, etc.). These could potentially be moved under the /_synapse/client/ prefix instead:

• /_matrix/client/(unstable|api/v1|r0)/login/cas/ticket
• /_matrix/client/unstable/registration/{medium}/submit_token
• /_matrix/client/unstable/add_threepid/email/submit_token
  • noted on add_threepid email confirmation emails link to /unstable/ namespace #9197
• /_matrix/client/unstable/add_threepid/msisdn/submit_token

Errors

• /_matrix/client/(unstable|api/v1|r0)/directory/list/room/{roomId} (implemented by ClientDirectoryListServer) supports an unspecced DELETE method.
  • Synapse supports unspecced DELETE /directory/list/room/<room ID> endpoint #13111
• /_matrix/client/(unstable|r0)/keys/upload/{deviceId} (implemented by KeyUploadServlet) in unspecced (the device ID is treated as optional by Synapse).
• There's a few endpoints that accept a txnId parameter at the end which is unspecced. (Search for callers of register_txn_path.) At least one caller of this also requires the txnId and shouldn't be registered without it.

Unimplemented

Specified endpoints that are not implemented in Synapse.

• /_matrix/client/r0/account/password/msisdn/requestToken, see spec. The corresponding email version is implemented.
• /_matrix/client/r0/rooms/{roomId}/aliases, see spec. This is only implemented as the unstable /_matrix/client/unstable/org\.matrix\.msc2432/rooms/{roomId}/aliases.

Deprecated

The specification has some deprecated endpoints as well. These are generally implemented by Synapse, but unless support for older versions of the spec are dropped, these cannot be dropped (e.g. the initialSync endpoint).

[clokep]

I think the next step here would be to:

• Identify endpoints that we would like to remove (e.g. they were an experiment and there's no value in them).
• Look at the logs from matrix.org and see if they've been used recently.
• Decide whether we can remove them. 😄

[tulir]

• The relation MSC isn't obsolete, it was just split up. The endpoints are now in MSC2675: Serverside aggregations of message relationships matrix-spec-proposals#2675 and partially MSC2674: Event Relationships matrix-spec-proposals#2674. (although the /send_relation endpoint is mostly useless since it does nothing that /send doesn't do)
• /aliases is unstable because Synapse doesn't support C-S r0.6.1 yet

[clokep]

All endpoints appear under /_matrix/client/unstable/, which is probably OK.

The MSC process actually says the opposite:

Note that unstable namespaces do not automatically inherit endpoints from stable namespaces: for example, the fact that /_matrix/client/r0/sync exists does not imply that /_matrix/client/unstable/com.example/sync exists.

[clokep]

The relation MSC isn't obsolete, it was just split up. The endpoints are now in matrix-org/matrix-doc#2675 and partially matrix-org/matrix-doc#2674. (although the /send_relation endpoint is mostly useless since it does nothing that /send doesn't do)

I must have missed that that MSC got replaced! Thanks for pointing this out!

/aliases is unstable because Synapse doesn't support C-S r0.6.1 yet

Fair enough, just documenting it. I thought we had an issue about this, but we don't seem to. I'll file a separate one.

[ShadowJonathan]

Should everything used by historical_admin_path_patterns be a part of this? (such as shutdown_room)

[clokep]

Should everything used by historical_admin_path_patterns be a part of this? (such as shutdown_room)

As I said in the description, this is tracked in a separate issue:

See #8177 about some of the admin APIs being exposed under /_matrix/client.

[clokep]

/_matrix/client/(unstable|api/v1|r0)/pushers/remove (implemented by PushersRemoveRestServlet).

I think this is matrix-org/matrix-doc#1757.