mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 18:08:37 +01:00
48d8f7202d
* Add HTTP 403 to possible profile responses
Some servers may not allow profile lookup over federation, and thus
respond to GET /_matrix/client/v3/profile/{userId} with an HTTP 403.
For example, Synapse can be configured to behave in this way by setting:
allow_profile_lookup_over_federation=false
Thus, this behavior already exists in the wild, and may cause issues for
clients such as https://github.com/vector-im/element-web/issues/17269.
Synapse could alter its behavior and return an HTTP 404 in these cases,
but amending the Spec seems preferable to align with extant behavior.
Further, allowing HTTP 403 gives clients more specific information as to
why a request has failed, enabling more precise error handling.
Signed-off-by: Dan Callahan <danc@element.io>
* Update changelogs/client_server/newsfragments/3530.clarification
Co-authored-by: Travis Ralston <travpc@gmail.com>
* Annotate misc data about error
Co-authored-by: Travis Ralston <travpc@gmail.com>
Co-authored-by: Travis Ralston <travisr@matrix.org>
235 lines
7.7 KiB
YAML
235 lines
7.7 KiB
YAML
# Copyright 2016 OpenMarket Ltd
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server Profile API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/v3
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
paths:
|
|
"/profile/{userId}/displayname":
|
|
put:
|
|
summary: Set the user's display name.
|
|
description: |-
|
|
This API sets the given user's display name. You must have permission to
|
|
set this user's display name, e.g. you need to have their `access_token`.
|
|
operationId: setDisplayName
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose display name to set.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
- in: body
|
|
name: displayName
|
|
description: The new display name information.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
example: {
|
|
"displayname": "Alice Margatroid"
|
|
}
|
|
properties:
|
|
displayname:
|
|
type: string
|
|
description: The new display name for this user.
|
|
responses:
|
|
200:
|
|
description: The display name was set.
|
|
examples:
|
|
application/json: {
|
|
}
|
|
schema:
|
|
type: object # empty json object
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/errors/rate_limited.yaml"
|
|
tags:
|
|
- User data
|
|
get:
|
|
summary: Get the user's display name.
|
|
description: |-
|
|
Get the user's display name. This API may be used to fetch the user's
|
|
own displayname or to query the name of other users; either locally or
|
|
on remote homeservers.
|
|
operationId: getDisplayName
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose display name to get.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
responses:
|
|
200:
|
|
description: The display name for this user.
|
|
examples:
|
|
application/json: {
|
|
"displayname": "Alice Margatroid"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
displayname:
|
|
type: string
|
|
description: The user's display name if they have set one, otherwise not present.
|
|
404:
|
|
description: There is no display name for this user or this user does not exist.
|
|
tags:
|
|
- User data
|
|
"/profile/{userId}/avatar_url":
|
|
put:
|
|
summary: Set the user's avatar URL.
|
|
description: |-
|
|
This API sets the given user's avatar URL. You must have permission to
|
|
set this user's avatar URL, e.g. you need to have their `access_token`.
|
|
operationId: setAvatarUrl
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose avatar URL to set.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
- in: body
|
|
name: avatar_url
|
|
description: The new avatar information.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
example: {
|
|
"avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
|
|
}
|
|
properties:
|
|
avatar_url:
|
|
type: string
|
|
format: uri
|
|
description: The new avatar URL for this user.
|
|
responses:
|
|
200:
|
|
description: The avatar URL was set.
|
|
examples:
|
|
application/json: {
|
|
}
|
|
schema:
|
|
type: object # empty json object
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/errors/rate_limited.yaml"
|
|
tags:
|
|
- User data
|
|
get:
|
|
summary: Get the user's avatar URL.
|
|
description: |-
|
|
Get the user's avatar URL. This API may be used to fetch the user's
|
|
own avatar URL or to query the URL of other users; either locally or
|
|
on remote homeservers.
|
|
operationId: getAvatarUrl
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose avatar URL to get.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
responses:
|
|
200:
|
|
description: The avatar URL for this user.
|
|
examples:
|
|
application/json: {
|
|
"avatar_url": "mxc://matrix.org/SDGdghriugerRg"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
avatar_url:
|
|
type: string
|
|
format: uri
|
|
description: The user's avatar URL if they have set one, otherwise not present.
|
|
404:
|
|
description: There is no avatar URL for this user or this user does not exist.
|
|
tags:
|
|
- User data
|
|
"/profile/{userId}":
|
|
get:
|
|
summary: Get this user's profile information.
|
|
description: |-
|
|
Get the combined profile information for this user. This API may be used
|
|
to fetch the user's own profile information or other users; either
|
|
locally or on remote homeservers. This API may return keys which are not
|
|
limited to `displayname` or `avatar_url`.
|
|
operationId: getUserProfile
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose profile information to get.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
responses:
|
|
200:
|
|
description: The avatar URL for this user.
|
|
examples:
|
|
application/json: {
|
|
"avatar_url": "mxc://matrix.org/SDGdghriugerRg",
|
|
"displayname": "Alice Margatroid"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
avatar_url:
|
|
type: string
|
|
format: uri
|
|
description: The user's avatar URL if they have set one, otherwise not present.
|
|
displayname:
|
|
type: string
|
|
description: The user's display name if they have set one, otherwise not present.
|
|
403:
|
|
x-addedInMatrixVersion: "1.2"
|
|
description: The server is unwilling to disclose whether the user exists and/or has profile information.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "Profile lookup over federation is disabled on this homeserver"
|
|
}
|
|
schema:
|
|
"$ref": "definitions/errors/error.yaml"
|
|
404:
|
|
description: There is no profile information for this user or this user does not exist.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_NOT_FOUND",
|
|
"error": "Profile not found"
|
|
}
|
|
schema:
|
|
"$ref": "definitions/errors/error.yaml"
|
|
tags:
|
|
- User data
|