diff --git a/proposals/1802-standardised-federation-response-format.md b/proposals/1802-standardised-federation-response-format.md new file mode 100644 index 00000000..6ddaa080 --- /dev/null +++ b/proposals/1802-standardised-federation-response-format.md @@ -0,0 +1,50 @@ +# Remove the '200' value from some federation responses + +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_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 (i.e. in a response with a 400 or a 404 status +code), 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` federation API, +but would break backward compatibility, thus would be harder to manage.