From ba8880546dcbb374ffd0339615ae8b2aa8880447 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Tue, 15 Oct 2019 13:54:52 +0200 Subject: [PATCH 1/6] Proposal for versions information on the identity server API --- proposals/xxxx-identity-versions.md | 42 +++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 proposals/xxxx-identity-versions.md diff --git a/proposals/xxxx-identity-versions.md b/proposals/xxxx-identity-versions.md new file mode 100644 index 00000000..7fbc3bd6 --- /dev/null +++ b/proposals/xxxx-identity-versions.md @@ -0,0 +1,42 @@ +# Versions information for identity servers + +The client-server spec currently specifies a `/versions` endpoint that allows +clients to know what version of that spec and unstable features are implemented +by the server. This allows MSC to be implemented and supported by both servers +and clients before they're merged and incorporated into the stable spec. + +This is also a feature we will need on the identity server spec, because +clients talk to them and need to be aware of unstables features (such as +[MSC2265](https://github.com/matrix-org/matrix-doc/pull/2265)) when they're +implemented by the identity server it's using (if there is one). + +## Proposal + +This proposal extends the [`/_matrix/identity/v2`](https://matrix.org/docs/spec/identity_service/r0.2.1#get-matrix-identity-api-v1) +endpoint's response by adding information about the supported versions of the +identity server specification and unstable features implemented by the server +to it. Because the current response for this endpoint is an empty object +(which is discarded by the client), the new response would look like: + +```json +{ + "unstable_features": { + "m.casefold_email_addresses": true + }, + "versions": [ + "r0.1.0", + "r0.2.0", + "r0.2.1", + ] +} +``` + +This response would follow the format of the [`/_matrix/client/versions`](https://matrix.org/docs/spec/client_server/unstable#get-matrix-client-versions) endpoint. + +## Alternative solutions + +An alternative solution to this issue would be to add a +`/_matrix/identity/versions` endpoint to the identity server specificiation. +This would however add more complexity by adding a new endpoint whereas there's +already an existing endpoint which seems relevant for handling this kind of +information. From 6bd28766880bc3df797f4ad23544aa6967859150 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Tue, 15 Oct 2019 13:59:22 +0200 Subject: [PATCH 2/6] MSC number --- .../{xxxx-identity-versions.md => 2320-identity-versions.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{xxxx-identity-versions.md => 2320-identity-versions.md} (100%) diff --git a/proposals/xxxx-identity-versions.md b/proposals/2320-identity-versions.md similarity index 100% rename from proposals/xxxx-identity-versions.md rename to proposals/2320-identity-versions.md From 4517506d57ad02c170116f52f44c2bf46d77bf52 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Tue, 15 Oct 2019 17:34:02 +0200 Subject: [PATCH 3/6] Incorporate review --- proposals/2320-identity-versions.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/proposals/2320-identity-versions.md b/proposals/2320-identity-versions.md index 7fbc3bd6..86121ef4 100644 --- a/proposals/2320-identity-versions.md +++ b/proposals/2320-identity-versions.md @@ -1,11 +1,11 @@ # Versions information for identity servers -The client-server spec currently specifies a `/versions` endpoint that allows -clients to know what version of that spec and unstable features are implemented +The client-server API currently specifies a `/versions` endpoint that allows +clients to know what version of that API and unstable features are implemented by the server. This allows MSC to be implemented and supported by both servers -and clients before they're merged and incorporated into the stable spec. +and clients before they're merged and incorporated into the stable API. -This is also a feature we will need on the identity server spec, because +This is also a feature we will need on the identity server API, because clients talk to them and need to be aware of unstables features (such as [MSC2265](https://github.com/matrix-org/matrix-doc/pull/2265)) when they're implemented by the identity server it's using (if there is one). @@ -14,14 +14,14 @@ implemented by the identity server it's using (if there is one). This proposal extends the [`/_matrix/identity/v2`](https://matrix.org/docs/spec/identity_service/r0.2.1#get-matrix-identity-api-v1) endpoint's response by adding information about the supported versions of the -identity server specification and unstable features implemented by the server +identity server API and unstable features implemented by the server to it. Because the current response for this endpoint is an empty object (which is discarded by the client), the new response would look like: ```json { "unstable_features": { - "m.casefold_email_addresses": true + "casefold_email_addresses": true }, "versions": [ "r0.1.0", @@ -31,12 +31,12 @@ to it. Because the current response for this endpoint is an empty object } ``` -This response would follow the format of the [`/_matrix/client/versions`](https://matrix.org/docs/spec/client_server/unstable#get-matrix-client-versions) endpoint. +This response would follow the format of the [`/_matrix/client/versions`](https://matrix.org/docs/spec/client_server/r0.5.0#get-matrix-client-versions) endpoint. ## Alternative solutions An alternative solution to this issue would be to add a -`/_matrix/identity/versions` endpoint to the identity server specificiation. +`/_matrix/identity/versions` endpoint to the identity server API. This would however add more complexity by adding a new endpoint whereas there's already an existing endpoint which seems relevant for handling this kind of information. From 52cd69eb754f8b3de970875418180b4e407d792d Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Thu, 7 Nov 2019 15:45:58 +0000 Subject: [PATCH 4/6] Split into two non-versioned endpoints --- proposals/2320-identity-versions.md | 40 +++++++++++++++++++---------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/proposals/2320-identity-versions.md b/proposals/2320-identity-versions.md index 86121ef4..0820d6e4 100644 --- a/proposals/2320-identity-versions.md +++ b/proposals/2320-identity-versions.md @@ -12,17 +12,15 @@ implemented by the identity server it's using (if there is one). ## Proposal -This proposal extends the [`/_matrix/identity/v2`](https://matrix.org/docs/spec/identity_service/r0.2.1#get-matrix-identity-api-v1) -endpoint's response by adding information about the supported versions of the -identity server API and unstable features implemented by the server -to it. Because the current response for this endpoint is an empty object -(which is discarded by the client), the new response would look like: +This proposal adds two endpoints to the identity server API. + +### `GET /_matrix/identity/versions` + +This endpoint serves information about the versions of the identity server API +this identity server supports. Its response uses the following format: ```json { - "unstable_features": { - "casefold_email_addresses": true - }, "versions": [ "r0.1.0", "r0.2.0", @@ -31,12 +29,26 @@ to it. Because the current response for this endpoint is an empty object } ``` -This response would follow the format of the [`/_matrix/client/versions`](https://matrix.org/docs/spec/client_server/r0.5.0#get-matrix-client-versions) endpoint. +### `GET /_matrix/identity/unstable_features` + +This endpoint serves information about the unstable features, i.e. features +specified in a MSC or an unstable version of the Matrix specification but not in +a stable one, supported by the server. Its response uses the following format: + +```json +{ + "unstable_features": { + "org.matrix.casefold_email_addresses": true + } +} +``` ## Alternative solutions -An alternative solution to this issue would be to add a -`/_matrix/identity/versions` endpoint to the identity server API. -This would however add more complexity by adding a new endpoint whereas there's -already an existing endpoint which seems relevant for handling this kind of -information. +Another solution which was considered was using the status check endpoint ([`GET +/_matrix/api/v1`](https://matrix.org/docs/spec/identity_service/latest#get-matrix-identity-api-v1)) +to serve this information. This solution was discarded because it's using a +versioned endpoint, which doesn't make sense to advertise the supported versions +of the API to use, and this endpoint was serving both the supported versions and +the supported unstable features, whereas it makes more sense to have each of +these pieces of information served on a different endpoint. From 0d4e2e75c7cd6a1d1da19befdf9ee6afcfb73bb2 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Wed, 5 Feb 2020 12:25:50 +0000 Subject: [PATCH 5/6] Remove unstable_features endpoint --- proposals/2320-identity-versions.md | 31 ++++++----------------------- 1 file changed, 6 insertions(+), 25 deletions(-) diff --git a/proposals/2320-identity-versions.md b/proposals/2320-identity-versions.md index 0820d6e4..7b75b480 100644 --- a/proposals/2320-identity-versions.md +++ b/proposals/2320-identity-versions.md @@ -1,14 +1,11 @@ # Versions information for identity servers The client-server API currently specifies a `/versions` endpoint that allows -clients to know what version of that API and unstable features are implemented -by the server. This allows MSC to be implemented and supported by both servers -and clients before they're merged and incorporated into the stable API. - -This is also a feature we will need on the identity server API, because -clients talk to them and need to be aware of unstables features (such as -[MSC2265](https://github.com/matrix-org/matrix-doc/pull/2265)) when they're -implemented by the identity server it's using (if there is one). +clients to know what version of that API are implemented by the server. +Identity servers could benefit from that endpoint as both homeservers and +clients interact with them, and therefore could know which features they can +expect a given identity server to implement by looking at the versions of the +API it claims to support. ## Proposal @@ -29,26 +26,10 @@ this identity server supports. Its response uses the following format: } ``` -### `GET /_matrix/identity/unstable_features` - -This endpoint serves information about the unstable features, i.e. features -specified in a MSC or an unstable version of the Matrix specification but not in -a stable one, supported by the server. Its response uses the following format: - -```json -{ - "unstable_features": { - "org.matrix.casefold_email_addresses": true - } -} -``` - ## Alternative solutions Another solution which was considered was using the status check endpoint ([`GET /_matrix/api/v1`](https://matrix.org/docs/spec/identity_service/latest#get-matrix-identity-api-v1)) to serve this information. This solution was discarded because it's using a versioned endpoint, which doesn't make sense to advertise the supported versions -of the API to use, and this endpoint was serving both the supported versions and -the supported unstable features, whereas it makes more sense to have each of -these pieces of information served on a different endpoint. +of the API to use. From 3c49ba9eb50aac15921e5fa27b0554f1b648c981 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Wed, 5 Feb 2020 12:29:12 +0000 Subject: [PATCH 6/6] Remove reference to second endpoint --- proposals/2320-identity-versions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2320-identity-versions.md b/proposals/2320-identity-versions.md index 7b75b480..ded50b3b 100644 --- a/proposals/2320-identity-versions.md +++ b/proposals/2320-identity-versions.md @@ -9,7 +9,7 @@ API it claims to support. ## Proposal -This proposal adds two endpoints to the identity server API. +This proposal adds the following endpoint to the identity server API. ### `GET /_matrix/identity/versions`