# MSC 1794 - Federation v2 Invite API

This proposal adds a new `/invite` API to federation that supports different
room versions.

## Motivation

It is planned for future room versions to be able to change the format of events
in various ways. To support this, all servers must know the room version
whenever they need to parse an event.  Currently the `/invite` API does not
include the room version, so the target server would be unable to parse the event included in the payload.
able to be parsed.

## Proposal

Add a new version of the invite API under the prefix `/_matrix/federation/v2`,
which has a payload of:

```
PUT /_matrix/federation/v2/invite/<room_id>/<event_id>

{
    "room_version": <room_version>,
    "event": { ... },
    "invite_room_state": [ ... ]
}
```

The differences between this and `v1` are:

1. The payload in `v1` is the event, while in `v2` the event is instead placed
   under an `"event"` key. This is for consistency with other APIs, and to allow
   extra data to be added to the request payload separately from the event.
2. A required field called `"room_version"` is added that specifies the room
   version.
3. The `"invite_room_state"` is moved from the `unsigned` section of the event
   to a top level key. The key `invite_room_state` being in the `event.unsigned`
   was a hack due to point 1. above.


The response is identical to `v1`, except that:

1. If the receiving server does not support the given room version the
   appropriate incompatible-room-version error is returned, in the same way
   as e.g. for `/make_join` APIs.
2. The response payload is no longer in the format of `[200, { ... }]`, and is
   instead simply the `{ ... }` portion. This fixes a historical accident to
   bring the invite API into line with the rest of the federation API.


If a call to `v2` `/invite` results in an unrecognised request exception **AND**
the room version is `1` or `2` then the sending server should retry the request
with the `v1` API.


## Alternatives


### Reusing V1 API

One alternative is to add a `room_version` query string parameter to the `v1`
`/invite` API in a similar way as for the `/make_join` APIs. However, older
servers would ignore the query string parameter while processing an incoming
`/invite` request, resulting in the server attempting to parse the event in the
old `v1` format. This would likely result in either a `400` or `500` response,
which the sending server could interpret as the receiving server not supporting
the room version.

This method, however, is fragile and could easily mask legitimate `400` and
`500` errors that are not due to not supporting the room version.


### Using V1 API for V1 room versions

Instead of all servers attempting to use the new API and falling back if the API
is not found, servers could instead always use the current API for V1 and V2
rooms.

However, this would not allow us to deprecate the `v1` API.