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 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).

## Proposal

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
{
    "versions": [
        "r0.1.0",
        "r0.2.0",
        "r0.2.1",
    ]
}
```

### `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.