|
|
@ -214,19 +214,36 @@ See the [Server Notices](#server-notices) module for more information.
|
|
|
|
### Transaction identifiers
|
|
|
|
### Transaction identifiers
|
|
|
|
|
|
|
|
|
|
|
|
The client-server API typically uses `HTTP PUT` to submit requests with
|
|
|
|
The client-server API typically uses `HTTP PUT` to submit requests with
|
|
|
|
a client-generated transaction identifier. This means that these
|
|
|
|
a client-generated transaction identifier in the HTTP path.
|
|
|
|
requests are idempotent. It **only** serves to identify new requests
|
|
|
|
|
|
|
|
from retransmits. After the request has finished, the `{txnId}` value
|
|
|
|
The purpose of the transaction ID is to allow the homeserver to distinguish a
|
|
|
|
should be changed (how is not specified; a monotonically increasing
|
|
|
|
new request from a retransmission of a previous request so that it can make
|
|
|
|
integer is recommended).
|
|
|
|
the request idempotent.
|
|
|
|
|
|
|
|
|
|
|
|
The scope of a transaction ID is a "client session", where that session
|
|
|
|
The transaction ID should **only** be used for this purpose.
|
|
|
|
is identified by a particular access token. When [refreshing](#refreshing-access-tokens)
|
|
|
|
|
|
|
|
an access token, the transaction ID's scope is retained. This means that
|
|
|
|
From the client perspective, after the request has finished, the `{txnId}`
|
|
|
|
if a client with token `A` uses `TXN1` as their transaction ID, refreshes
|
|
|
|
value should be changed by for the next request (how is not specified; a
|
|
|
|
the token to `B`, and uses `TXN1` again it'll be assumed to be a duplicate
|
|
|
|
monotonically increasing integer is recommended).
|
|
|
|
request and ignored. If the client logs out and back in between the `A` and
|
|
|
|
|
|
|
|
`B` tokens, `TXN1` could be used once for each.
|
|
|
|
The homeserver should identify a request as a retransmission if the
|
|
|
|
|
|
|
|
transaction ID is the same as a previous request, and the path of the
|
|
|
|
|
|
|
|
HTTP request is the same.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Where a retransmission has been identified, the homeserver should return
|
|
|
|
|
|
|
|
the same HTTP response code and content as the original request.
|
|
|
|
|
|
|
|
For example, `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`
|
|
|
|
|
|
|
|
would return a `200 OK` with the `event_id` of the original request in
|
|
|
|
|
|
|
|
the response body.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
As well as the HTTP path, the scope of a transaction ID is a "client
|
|
|
|
|
|
|
|
session", where that session is identified by a particular access token.
|
|
|
|
|
|
|
|
When [refreshing](#refreshing-access-tokens) an access token, the
|
|
|
|
|
|
|
|
transaction ID's scope is retained. This means that if a client with
|
|
|
|
|
|
|
|
token `A` uses `TXN1` as their transaction ID, refreshes the token to
|
|
|
|
|
|
|
|
`B`, and uses `TXN1` again it'll be assumed to be a duplicate request
|
|
|
|
|
|
|
|
and ignored. If the client logs out and back in between the `A` and `B`
|
|
|
|
|
|
|
|
tokens, `TXN1` could be used once for each.
|
|
|
|
|
|
|
|
|
|
|
|
Some API endpoints may allow or require the use of `POST` requests
|
|
|
|
Some API endpoints may allow or require the use of `POST` requests
|
|
|
|
without a transaction ID. Where this is optional, the use of a `PUT`
|
|
|
|
without a transaction ID. Where this is optional, the use of a `PUT`
|
|
|
|