MSC2233: Unauthenticated Capabilities API #2233
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| # Unauthenticated Capabilities API | ||
|
|
||
| ## Introduction | ||
|
|
||
| The existing [Capabilities | ||
| API](https://matrix.org/docs/spec/client_server/r0.5.0#get-matrix-client-r0-capabilities) | ||
| is an authenticated endpoint that allows a Matrix server to advertise which | ||
| services it does and does not provide. The authentication is due to the | ||
| possibility of suggesting that some capabilities are supported for some | ||
| users, while the same may not be supported for others (imagine a regular user | ||
| querying this endpoint, and then an application service doing the same). | ||
|
|
||
| While the ability to scope the capabilities to the requesting user is very | ||
| useful, there are use cases that could benefit from this API being called | ||
| from an unauthenticated user as well. For instance, information that a user | ||
|
There was a problem hiding this comment. I'm not convinced that any of the examples that follow need a capabilities endpoint.
|
||
| would like to know about a server before they sign up, such as whether the | ||
| server sends message content through a media-scanner, or whether the server | ||
|
There was a problem hiding this comment.
is this really a thing that is better exposed over an API than described in a policy document for a human to read? There was a problem hiding this comment. I can still see a usecase for values that sites may want to pull and present their own filtering for. |
||
| allows E2EE session key backup. A client could query this information before | ||
|
There was a problem hiding this comment.
surely this should be under There was a problem hiding this comment. Discussed in #2233 (comment) |
||
| they sign up. Another usecase is websites that lists public Matrix servers | ||
| could automatically query whether each server supports features that may be | ||
| important to users, without having to authenticate to the server to do so. | ||
|
|
||
|
|
||
| ## Proposal | ||
|
|
||
| Add two new API endpoints: | ||
|
|
||
| * `GET /_matrix/client/r0/capabilities/server` | ||
| * `GET /_matrix/client/r0/capabilities/user` | ||
|
|
||
| `/capabilities/user` would be exactly the same as the existing | ||
| `/capabilities` endpoint, which requires authentication as what it returns is | ||
| scoped to the user making the request. | ||
|
|
||
| `/capabilities/server` would not require authentication and should return | ||
| information about the server's capabilities that would be pertinent to | ||
| non-authenticated users. | ||
|
|
||
| The existing `/capabilities` API would be replaced by `/capabilities/user`. | ||
|
There was a problem hiding this comment. Due to the backwards compatibility section below, it should be deprecated with intent to replace, not replaced. |
||
|
|
||
| ## Backwards compatibility | ||
|
|
||
| Servers supporting older versions of the Client Server API should continue to | ||
| answer `/capabilities` requests as if they were `/capabilities/user`. They | ||
| MUST NOT redirect the request to `/capabilities/user`, as this may confuse | ||
| older clients. | ||
|
|
||
| ## Tradeoffs | ||
anoadragon453 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| The various features could have their own unauthenticated endpoints to check | ||
| whether or not the server supports them, but consolidating them into a single | ||
| API potentially reduces our API surface significantly. | ||
|
|
||
| ## Conclusion | ||
|
|
||
| Adding an unauthenticated version of the `/capabilities` API gives servers | ||
| the flexibility to inform the general public about what features they | ||
| support, rather than only those that already have an account with them. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm a bit concerned about the proliferation of 'features' endpoints (
/versions,/_matrix/client/r0/capabilities/server,/_matrix/client/r0/capabilities/user,/_matrix/media/r0/config): the main concern being that it's not obvious what goes where.Indeed, ISTR the main driver for
/_matrix/client/r0/capabilitiesas opposed to/versionswas that it required authentication...There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was going to say that putting feature capabilities on
/versionsdoesn't make sense given the name, but then I realized we're already doing that :|These things could be added to
/versionsthen if we think that that's not too weird.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree with @richvdh that we have far too many endpoints for similar things, although I was never really onboard with putting features inside
/versions.To be honest I wish we had just named them something like
/_matrix/${apiname}/config/so it was at least consistent.If we could go back in time, I wish we hadn't polluted /versions.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/versionsfeatures anunstable_featureskey which is supposed to be used for additional features that the server supported which are not included in the spec. The examples described in this MSC do not fit these terms.We could add another key, like
config, which would be general enough to hold random public configuration values the server has decided to set up.Or we can move it to its own API. With regards to this MSC, I think it'd be easy enough to say whether information should go in
/versions,/_matrix/client/r0/capabilities/*, or/_matrix/media/r0/config.And then deciding between
capabilities/serverandcapabilities/userwould just be "does this information need to either rely on a user, or is potentially sensitive"? Then it goes in/user, otherwise/server.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we actually have a strong use case for this MSC at all? If this MSC also had a capability it wanted to add then we could discuss the merits of that capability in the context of a new API vs some other solution. Without an example, the distinction between the endpoints is unclear and seems to be building a framework for a feature we don't know if we even want.
If we don't have an example for this API, this MSC should be put on the backburner or closed until we need it imo. I also have general concerns with an unauthenticated version of the endpoint because the cases presented thus far are better solved in other ways.