Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-04-03 01:34:10 +02:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Propose a backward-compatible option instead of an incompatible one

Browse source
This commit is contained in:
Brendan Abolivier 2019-01-14 16:17:40 +00:00
parent d318ff95f3
commit 749b1777fa
1 changed files with 18 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
proposals/1802-standardised-federation-response-format.md
View file

@ -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 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 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 features, and has been left as is because fixing it would induce backward
incompatibility. With r0 approaching, and already including features with incompatibility.
backward compatibility issues (e.g.
[MSC1711](https://github.com/matrix-org/matrix-doc/pull/1711)), this is likely This proposal proposes a backward compatible alternative
the right timing to address this issue.
## Proposal ## Proposal
Change the responses with a 200 status code for the following federation Add a new version of the following endpoints under the prefix
endpoints: `/_matrix/federation/v2`:
* `PUT /_matrix/federation/v1/send/{txnId}` * `PUT /_matrix/federation/v2/send/{txnId}`
* `PUT /_matrix/federation/v1/send_join/{roomId}/{eventId}` * `PUT /_matrix/federation/v2/send_join/{roomId}/{eventId}`
* `PUT /_matrix/federation/v1/invite/{roomId}/{eventId}` * `PUT /_matrix/federation/v2/send_leave/{roomId}/{eventId}`
* `PUT /_matrix/federation/v1/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 res
@ -37,19 +36,12 @@ res
Where `res` is the JSON object containing the response to a request directed at Where `res` is the JSON object containing the response to a request directed at
one of the affected endpoints. one of the affected endpoints.
## Potential issues 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.
As it's already been mentioned in the proposal's introduction, this would induce ## Alternative solutions
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 An alternative solution would be to make the change in the `v1` fedration API,
response formats would be accepted on the affected endpoints. This would give but would break backward compatibility, thus would be harder to manage.
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.