matrix-spec/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) 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:

{
    "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:

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