matrix-spec-proposals/proposals/2320-identity-versions.md

# Versions information for identity servers

The client-server API currently specifies a `/versions` endpoint that allows
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

This proposal adds the following endpoint 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
{
    "versions": [
        "r0.1.0",
        "r0.2.0",
        "r0.2.1",
    ]
}
```

## Alternative solutions

Another solution which was considered was using the status check endpoint ([`GET
/_matrix/api/v1`](https://matrix.org/docs/spec/identity_service/r0.2.0#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.
Proposal for versions information on the identity server API 5 years ago			`# Versions information for identity servers`

Incorporate review 5 years ago			The client-server API currently specifies a `/versions` endpoint that allows
Remove unstable_features endpoint 5 years ago			`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 for versions information on the identity server API 5 years ago
			`## Proposal`

Remove reference to second endpoint 5 years ago			`This proposal adds the following endpoint to the identity server API.`
Split into two non-versioned endpoints 5 years ago
			### `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:`
Proposal for versions information on the identity server API 5 years ago
			```json
			`{`
			`"versions": [`
			`"r0.1.0",`
			`"r0.2.0",`
			`"r0.2.1",`
			`]`
			`}`
			```

			`## Alternative solutions`

Split into two non-versioned endpoints 5 years ago			Another solution which was considered was using the status check endpoint ([`GET
Fix non-permanent links in MSCs to withstand time (#3422) As "unstable" changes and "latest" becomes no more, these sorts of links should be updated to reference the approximate section they intended to reference at the time of writing. This change tries to link up the relevant bits for the time of the proposal, though it's not a perfect match. Some MSCs were brought into the spec before an API version could be assigned to the "old" text, so github permalinks are used instead. 3 years ago			/_matrix/api/v1`](https://matrix.org/docs/spec/identity_service/r0.2.0#get-matrix-identity-api-v1))
Split into two non-versioned endpoints 5 years ago			`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`
Remove unstable_features endpoint 5 years ago			`of the API to use.`