Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2025-12-28 19:48:37 +01: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
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
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
backward compatibility issues. However, proposals that have already been merged
at the time this one is being written already induce similar issues.
## Alternative solutions
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.
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.