mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 18:08:37 +01:00
7bd48ca9c7
If an object definition already has an example, we shouldn't try to extend that definition by adding examples derived from the individual properties. Doing so is confusing, and there is no way to inhibit it when it is not desired. It's also not what the RapiDoc viewere does, so we end up with examples being inconsistent.
117 lines
4.3 KiB
YAML
117 lines
4.3 KiB
YAML
# Copyright 2018 New Vector Ltd
|
|
# Copyright 2020 The Matrix.org Foundation C.I.C.
|
|
#
|
|
# 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 Federation User Device Management API"
|
|
version: "1.0.0"
|
|
host: localhost:8448
|
|
schemes:
|
|
- https
|
|
basePath: /_matrix/federation/v1
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
paths:
|
|
"/user/devices/{userId}":
|
|
get:
|
|
summary: Gets all of the user's devices
|
|
description: Gets information on all of the user's devices
|
|
operationId: getUserDevices
|
|
security:
|
|
- signedRequest: []
|
|
parameters:
|
|
- in: path
|
|
name: userId
|
|
type: string
|
|
required: true
|
|
description: |-
|
|
The user ID to retrieve devices for. Must be a user local to the
|
|
receiving homeserver.
|
|
x-example: "@alice:example.org"
|
|
responses:
|
|
200:
|
|
description: The user's devices.
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
description: The user ID devices were requested for.
|
|
example: "@alice:example.org"
|
|
stream_id:
|
|
type: integer
|
|
description: |-
|
|
A unique ID for a given user_id which describes the version of
|
|
the returned device list. This is matched with the `stream_id`
|
|
field in `m.device_list_update` EDUs in order to incrementally
|
|
update the returned device_list.
|
|
example: 5
|
|
devices:
|
|
type: array
|
|
description: The user's devices. May be empty.
|
|
items:
|
|
type: object
|
|
title: User Device
|
|
properties:
|
|
device_id:
|
|
type: string
|
|
description: The device ID.
|
|
example: "JLAFKJWSCS"
|
|
keys:
|
|
type: object
|
|
description: Identity keys for the device.
|
|
$ref: "../client-server/definitions/device_keys.yaml"
|
|
device_display_name:
|
|
type: string
|
|
description: Optional display name for the device.
|
|
example: "Alice's Mobile Phone"
|
|
required: ['device_id', 'keys']
|
|
master_key:
|
|
type: object
|
|
description: |-
|
|
The user\'s master cross-signing key.
|
|
allOf:
|
|
- $ref: ../client-server/definitions/cross_signing_key.yaml
|
|
- example: {
|
|
"user_id": "@alice:example.com",
|
|
"usage": ["master"],
|
|
"keys": {
|
|
"ed25519:base64+master+public+key": "base64+master+public+key",
|
|
}
|
|
}
|
|
self_signing_key:
|
|
type: object
|
|
description: |-
|
|
The user\'s self-signing key.
|
|
allOf:
|
|
- $ref: ../client-server/definitions/cross_signing_key.yaml
|
|
- example: {
|
|
"user_id": "@alice:example.com",
|
|
"usage": ["self_signing"],
|
|
"keys": {
|
|
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
|
|
},
|
|
"signatures": {
|
|
"@alice:example.com": {
|
|
"ed25519:base64+master+public+key": "signature+of+self+signing+key"
|
|
}
|
|
}
|
|
}
|
|
required: ['user_id', 'stream_id', 'devices']
|