From d318ff95f3e835687df9d3411cf52613475516a3 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Mon, 14 Jan 2019 11:55:27 +0000 Subject: [PATCH] MSC1802: Standardised federation response formats --- ...standardised-federation-response-format.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 proposals/1802-standardised-federation-response-format.md diff --git a/proposals/1802-standardised-federation-response-format.md b/proposals/1802-standardised-federation-response-format.md new file mode 100644 index 00000000..736cbbd3 --- /dev/null +++ b/proposals/1802-standardised-federation-response-format.md @@ -0,0 +1,55 @@ +# 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. With r0 approaching, and already including features with +backward compatibility issues (e.g. +[MSC1711](https://github.com/matrix-org/matrix-doc/pull/1711)), this is likely +the right timing to address this issue. + +## Proposal + +Change the responses with a 200 status code for the following federation +endpoints: + +* `PUT /_matrix/federation/v1/send/{txnId}` +* `PUT /_matrix/federation/v1/send_join/{roomId}/{eventId}` +* `PUT /_matrix/federation/v1/invite/{roomId}/{eventId}` +* `PUT /_matrix/federation/v1/send_leave/{roomId}/{eventId}` + +From a response using this format: + +``` +[ + 200, + res +] +``` + +To a response using this format: + +``` +res +``` + +Where `res` is the JSON object containing the response to a request directed at +one of the affected endpoints. + +## Potential issues + +As it's already been mentioned in the proposal's introduction, this would induce +backward compatibility issues. However, proposals that have already been merged +at the time this one is being written already induce similar issues. + +As a mitigation solution, we could have a transition period during which both +response formats would be accepted on the affected endpoints. This would give +people time to update their homeservers to a version supporting the new one +without breaking federation entirely. + +## Conclusion + +Such a change would make the federation API specifications more standardised, +but would induce backward incompatible changes. However, with r0 coming up soon, +this is likely the best timing to address this issue.