Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-04 18:54:09 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

s2s/query: clarify profile behaviour and API responses

Browse source 
Signed-off-by: famfo <famfo@famfo.xyz>
This commit is contained in:
famfo 2026-03-02 01:38:54 +01:00
parent be21886a73
commit 5790b2f990
No known key found for this signature in database
2 changed files with 28 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/server_server/newsfragments/2326.clarification Normal file
View file

@ -0,0 +1 @@
Clarify the s2s profile query behaviour and responses.

42
data/api/server-server/query.yaml
View file

@ -111,11 +111,11 @@ paths:
summary: Query for profile information about a given user summary: Query for profile information about a given user
description: |- description: |-
Performs a query to get profile information, such as a display name or avatar, Performs a query to get profile information, such as a display name or avatar,
for a given user. Homeservers should only query profiles for users that belong for a given user. Homeservers MUST only query profiles for users that belong
to the target server (identified by the [server name](/appendices/#server-name) to the target server (identified by the [server name](/appendices/#server-name)
in the user ID). in the user ID).
Servers may wish to cache the response to this query to avoid requesting the Servers MAY wish to cache the response to this query to avoid requesting the
information too often. information too often.
Servers MAY deny profile look-up over federation by responding with 403 and an Servers MAY deny profile look-up over federation by responding with 403 and an
@ -126,7 +126,7 @@ paths:
parameters: parameters:
- in: query - in: query
name: user_id name: user_id
description: The user ID to query. Must be a user local to the receiving homeserver. description: The user ID to query. MUST be a user local to the receiving homeserver.
required: true required: true
example: "@someone:example.org" example: "@someone:example.org"
schema: schema:
@ -134,9 +134,9 @@ paths:
- in: query - in: query
name: field name: field
description: |- description: |-
The field to query. If specified, the server will only return the given field The field of the profile to query. If specified, the server MUST only return the
in the response. If not specified, the server will return the full profile for given field in the response. If not specified, the server MUST return the full,
the user. public, profile for the user.
schema: schema:
type: string type: string
enum: enum:
@ -146,12 +146,12 @@ paths:
"200": "200":
description: |- description: |-
The profile for the user. If a `field` is specified in the request, only the The profile for the user. If a `field` is specified in the request, only the
matching field should be included in the response. If no `field` was specified, matching field MUST included in the response. If no `field` was specified,
the response should include the fields of the user's profile that can be made the response MUST include the fields of the user's profile that can be made
public, such as the display name and avatar. public, such as the display name and avatar.
If the user does not have a particular field set on their profile, the server If the user does not have a particular field set on their profile, the server
should exclude it from the response body or give it the value `null`. MUST either exclude it from the response body or give it the value `null`.
content: content:
application/json: application/json:
schema: schema:
@ -160,20 +160,32 @@ paths:
displayname: displayname:
type: string type: string
description: |- description: |-
The display name of the user. May be omitted if the user does not have a The display name of the user. MUST either be omitted or set to `null` if
display name set. the user does not have a display name set.
example: John Doe example: John Doe
avatar_url: avatar_url:
type: string type: string
description: |- description: |-
The avatar URL for the user's avatar. May be omitted if the user does not The avatar URL for the user's avatar. MUST either be omitted or set to
have an avatar set. `null` if the user does not have an avatar set.
example: mxc://matrix.org/MyC00lAvatar example: mxc://example.org/MyC00lAvatar
examples: examples:
response: response:
value: { value: {
"displayname": "John Doe", "displayname": "John Doe",
"avatar_url": "mxc://matrix.org/MyC00lAvatar" "avatar_url": "mxc://example.org/MyC00lAvatar"
}
"400":
description: A given `field` in the query is invalid.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNRECOGNIZED",
"error": "Field m.room.name is not in valid subset valid profile fields"
} }
"403": "403":
x-addedInMatrixVersion: "1.12" x-addedInMatrixVersion: "1.12"