wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Describe return codes for account data endpoints + minor clarifications (#1155)

Browse source
This commit is contained in:
David Robertson 2022-07-14 13:01:56 +01:00 • committed by GitHub
parent 56400ab9a0
commit f9028acf8e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 127 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/1155.clarification Normal file
View file

@ -0,0 +1 @@
Describe return codes for account data endpoints, and clarify that per-room data does not inherit from the global data.

7
content/client-server-api/modules/account_data.md
View file

@ -7,9 +7,12 @@ type: module
Clients can store custom config data for their account on their
homeserver. This account data will be synced between different devices
and can persist across installations on a particular device. Users may
only view the account data for their own account
only view the account data for their own account.
The account\_data may be either global or scoped to a particular rooms.
The account data may be either global or scoped to a particular room.
There is no inheritance mechanism here: a given `type` of data missing
from a room's account data does not fall back to the global account
data with the same `type`.
#### Events

123
data/api/client-server/account-data.yaml
View file

@ -71,6 +71,39 @@ paths:
application/json: {}
schema:
type: object
400:
description: |-
The request body is not a JSON object. Errcode: `M_BAD_JSON`
or `M_NOT_JSON`.
examples:
application/json: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
description: |-
The access token provided is not authorized to modify this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
405:
examples:
application/json: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
description: |-
This `type` of account data is controlled by the server; it cannot be
modified by clients. Errcode: `M_BAD_JSON`.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
tags:
- User data
get:
@ -106,11 +139,33 @@ paths:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
403:
description: |-
The access token provided is not authorized to retrieve this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: |-
No account data has been provided for this user with the given `type`.
Errcode: `M_NOT_FOUND`.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room account data not found."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
tags:
- User data
"/user/{userId}/rooms/{roomId}/account_data/{type}":
put:
summary: Set some account_data for the user.
summary: Set some account_data for the user that is specific to a room.
description: |-
Set some account_data for the client on a given room. This config is only
visible to the user that set the account_data. The config will be synced to
@ -159,10 +214,44 @@ paths:
application/json: {}
schema:
type: object
400:
description: |-
The request body is not a JSON object (errcode `M_BAD_JSON` or
`M_NOT_JSON`), or the given `roomID` is not a valid room ID
(errcode `M_INVALID_PARAM`).
examples:
application/json: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
description: |-
The access token provided is not authorized to modify this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
405:
description: |-
This `type` of account data is controlled by the server; it cannot be
modified by clients. Errcode: `M_BAD_JSON`.
examples:
application/json: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
tags:
- User data
get:
summary: Get some account_data for the user.
summary: Get some account_data for the user that is specific to a room.
description: |-
Get some account_data for the client on a given room. This config is only
visible to the user that set the account_data.
@ -201,5 +290,35 @@ paths:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
400:
description: |-
The given `roomID` is not a valid room ID. Errcode: `M_INVALID_PARAM`.
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
"error": "@notaroomid:example.org is not a valid room ID."
}
403:
description: |-
The access token provided is not authorized to retrieve this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: |-
No account data has been provided for this user and this room with the
given `type`. Errcode: `M_NOT_FOUND`.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room account data not found."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
tags:
- User data