From 749b1777fa549ba1e6c156d26dfb43b5eb88127f Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Mon, 14 Jan 2019 16:17:40 +0000 Subject: [PATCH] Propose a backward-compatible option instead of an incompatible one --- ...standardised-federation-response-format.md | 44 ++++++++----------- 1 file changed, 18 insertions(+), 26 deletions(-) diff --git a/proposals/1802-standardised-federation-response-format.md b/proposals/1802-standardised-federation-response-format.md index 736cbbd3..f4cefc8f 100644 --- a/proposals/1802-standardised-federation-response-format.md +++ b/proposals/1802-standardised-federation-response-format.md @@ -4,22 +4,21 @@ 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. +incompatibility. + +This proposal proposes a backward compatible alternative ## Proposal -Change the responses with a 200 status code for the following federation -endpoints: +Add a new version of the following endpoints under the prefix +`/_matrix/federation/v2`: -* `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}` +* `PUT /_matrix/federation/v2/send/{txnId}` +* `PUT /_matrix/federation/v2/send_join/{roomId}/{eventId}` +* `PUT /_matrix/federation/v2/send_leave/{roomId}/{eventId}` -From a response using this format: +Which are the exact same endpoints as their equivalents under the `v1` prefix, +except for the response format, which changes from: ``` [ @@ -28,7 +27,7 @@ From a response using this format: ] ``` -To a response using this format: +To: ``` res @@ -37,19 +36,12 @@ 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. +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. -## Conclusion +## Alternative solutions -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. +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.