MSC1802: Remove the '200' value from some federation responses

proposals/1802-standardised-federation-response-format.md

@@ -0,0 +1,51 @@
+# Standardised federation response formats
+
+Some responses formats in the federation API specifications use the form `[200,
+res]` in which `res` is the JSON object containing the actual response for the
+affected endpoints. This was due to a mishap while building synapse's federation
+features, and has been left as is because fixing it would induce backward
+incompatibility.
+
+This proposal proposes a backward compatible alternative
+
+## Proposal
+
+Add a new version of the following endpoints under the prefix
+`/_matrix/federation/v2`:
+
+* `PUT /_matrix/federation/v2/send/{txnId}`
+* `PUT /_matrix/federation/v2/send_join/{roomId}/{eventId}`
+* `PUT /_matrix/federation/v2/send_leave/{roomId}/{eventId}`
+
+Which are the exact same endpoints as their equivalents under the `v1` prefix,
+except for the response format, which changes from:
+
+```
+[
+    200,
+    res
+]
+```
+
+To:
+
+```
+res
+```
+
+Where `res` is the JSON object containing the response to a request directed at
+one of the affected endpoints.
+
+This proposal doesn't address the `PUT
+/_matrix/federation/v1/invite/{roomId}/{eventId}` endpoint since
+[MSC1794](https://github.com/matrix-org/matrix-doc/pull/1794) already takes care
+of it.
+
+If a call to any of the `v2` endpoints described in this proposal results in an
+unrecognised request exception, then the sending server should retry the request
+with the `v1` API.
+
+## Alternative solutions
+
+An alternative solution would be to make the change in the `v1` fedration API,
+but would break backward compatibility, thus would be harder to manage.