diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 7a82406c..cb7087b9 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -4237,6 +4237,19 @@ not have to perform extra round trips to query it. {{% http-api spec="client-server" api="mutual_rooms" %}} +#### Server behaviour + +The server may decide that the response to this endpoint is too large, and only return a +subset of the results. In this case, the server should populate the optional field `next_batch` +with an [opaque identifier](/appendices/#opaque-identifiers). The client may then supply +the identifier as the `from` query parameter in a subsequent request, along with the original +`user_id`, to fetch the next batch of responses. This will continue until the server no longer +inserts `next_batch`, meaning there are no further results. + +Batch tokens generated by this endpoint SHOULD be valid for at least 10 minutes, after which, +tokens can expire. Expired tokens SHOULD be handled similar to invalid tokens, and return +a 400 response. + ## Modules Modules are parts of the Client-Server API which are not universal to diff --git a/data/api/client-server/mutual_rooms.yaml b/data/api/client-server/mutual_rooms.yaml index 4d03d6a7..2d764e6c 100644 --- a/data/api/client-server/mutual_rooms.yaml +++ b/data/api/client-server/mutual_rooms.yaml @@ -40,7 +40,10 @@ paths: - in: query name: from required: false - description: A pagination token from a previous result. + description: |- + A pagination token from a previous result. This should be a `next_batch` result from + a previous call to this endpoint. If not provided, the server will return the first + batch of results. example: next_batch_token schema: type: string @@ -83,7 +86,9 @@ paths: "400": description: |- - The user ID provided was [non-compliant](/appendices/#historical-user-ids). + Part of the request was invalid. The `from` token provided was invalid or expired, + the `user_id` parameter was missing, [non-compliant](/appendices/#historical-user-ids), + or was the sender's own user ID. content: application/json: schema: