async-matrix 0.1.3 → 1.0.0

data/data/matrix-spec/api/client-server/device_management.yaml

@@ -0,0 +1,314 @@
+# 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server device management API
+  version: 1.0.0
+paths:
+  /devices:
+    get:
+      summary: List registered devices for the current user
+      description: Gets information about all devices for the current user.
+      operationId: getDevices
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: Device information
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  devices:
+                    type: array
+                    description: A list of all registered devices for this user.
+                    items:
+                      $ref: definitions/client_device.yaml
+              examples:
+                response:
+                  value: {
+                    "devices": [
+                      {
+                        "device_id": "QBUAZIFURK",
+                        "display_name": "android",
+                        "last_seen_ip": "1.2.3.4",
+                        "last_seen_ts": 1474491775024
+                      }
+                    ]
+                  }
+      tags:
+        - Device management
+  "/devices/{deviceId}":
+    get:
+      summary: Get a single device
+      description: Gets information on a single device, by device id.
+      operationId: getDevice
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: deviceId
+          description: The device to retrieve.
+          required: true
+          example: QBUAZIFURK
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Device information
+          content:
+            application/json:
+              schema:
+                $ref: definitions/client_device.yaml
+              examples:
+                response:
+                  value: {
+                    "device_id": "QBUAZIFURK",
+                    "display_name": "android",
+                    "last_seen_ip": "1.2.3.4",
+                    "last_seen_ts": 1474491775024
+                  }
+        "404":
+          description: The current user has no device with the given ID.
+      tags:
+        - Device management
+    put:
+      summary: Create or update a device
+      x-changedInMatrixVersion:
+        "1.17": The ability to create new devices was added.
+      description: |-
+        Updates the metadata on the given device, or creates a new device.
+
+        The ability to create new devices is only available to application
+        services: regular clients may only update existing devices.
+
+        When a new device was created, the homeserver MUST return a 201 HTTP
+        status code. It MUST return a 200 HTTP status code if a device was
+        updated.
+
+        This endpoint is rate-limited for device creation. Servers MAY use login
+        rate limits.
+      operationId: updateDevice
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: deviceId
+          description: The device to update.
+          required: true
+          example: QBUAZIFURK
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                display_name:
+                  type: string
+                  description: |-
+                    The new display name for this device. If not given, the
+                    display name is unchanged.
+              example: {
+                "display_name": "My other phone"
+              }
+        description: New information for the device.
+        required: true
+      responses:
+        "200":
+          description: The device was successfully updated.
+          content:
+            application/json:
+              schema:
+                type: object  # empty json object
+              examples:
+                response:
+                  value: {}
+        "201":
+          description: |-
+            The device was successfully created by the application service.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "404":
+          description: The current user has no device with the given ID.
+      tags:
+        - Device management
+    delete:
+      summary: Delete a device
+      x-changedInMatrixVersion:
+        "1.17": |-
+          This endpoint no longer requires User-Interactive Authentication when used by an
+          application service.
+      description: |-
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
+        except when used by an application service.
+
+        Deletes the given device, and invalidates any access token associated with it.
+
+        {{% boxes/warning %}}
+        When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available, with the `action=org.matrix.device_delete` and `device_id={deviceId}` parameters.
+        {{% /boxes/warning %}}
+      operationId: deleteDevice
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: deviceId
+          description: The device to delete.
+          required: true
+          example: QBUAZIFURK
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                auth:
+                  description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+        required: true
+      responses:
+        "200":
+          description: |-
+            The device was successfully removed, or had been removed
+            previously.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+      tags:
+        - Device management
+  /delete_devices:
+    post:
+      summary: Bulk deletion of devices
+      x-changedInMatrixVersion:
+        "1.17": |-
+          This endpoint no longer requires User-Interactive Authentication when used by an
+          application service.
+      description: |-
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
+        except when used by an application service.
+
+        Deletes the given devices, and invalidates any access token associated with them.
+
+        {{% boxes/warning %}}
+        When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available.
+        {{% /boxes/warning %}}
+      operationId: deleteDevices
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                devices:
+                  type: array
+                  description: The list of device IDs to delete.
+                  items:
+                    type: string
+                    description: A list of device IDs.
+                  example:
+                    - QBUAZIFURK
+                    - AUIECTSRND
+                auth:
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+                  description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API.
+              required:
+                - devices
+        required: true
+      responses:
+        "200":
+          description: |-
+            The devices were successfully removed, or had been removed
+            previously.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+      tags:
+        - Device management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/data/matrix-spec/api/client-server/directory.yaml

@@ -0,0 +1,318 @@
+# 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Directory API
+  version: 1.0.0
+paths:
+  "/directory/room/{roomAlias}":
+    put:
+      summary: Create a new mapping from room alias to room ID.
+      operationId: setRoomAlias
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomAlias
+          description: |
+            The room alias to set. Its format is defined
+            [in the appendices](/appendices/#room-aliases).
+          required: true
+          example: "#monkeys:matrix.org"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                room_id:
+                  type: string
+                  description: The room ID to set.
+              required:
+                - room_id
+              example: {
+                "room_id": "!abnjk1jdasj98:capuchins.com"
+              }
+        description: Information about this room alias.
+        required: true
+      responses:
+        "200":
+          description: The mapping was created.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "400":
+          description: The given `roomAlias` is not a valid room alias.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Room alias invalid"
+                  }
+        "409":
+          description: A room alias with that name already exists.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNKNOWN",
+                    "error": "Room alias #monkeys:matrix.org already exists."
+                  }
+      tags:
+        - Room directory
+    get:
+      summary: Get the room ID corresponding to this room alias.
+      description: |-
+        Requests that the server resolve a room alias to a room ID.
+
+        The server will use the federation API to resolve the alias if the
+        domain part of the alias does not correspond to the server's own
+        domain.
+      operationId: getRoomIdByAlias
+      parameters:
+        - in: path
+          name: roomAlias
+          description: |
+            The room alias. Its format is defined
+            [in the appendices](/appendices/#room-aliases).
+          required: true
+          example: "#monkeys:matrix.org"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The room ID and other information for this alias.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  room_id:
+                    type: string
+                    description: The room ID for this room alias.
+                  servers:
+                    type: array
+                    description: A list of servers that are aware of this room alias.
+                    items:
+                      type: string
+                      description: A server which is aware of this room alias.
+              examples:
+                response:
+                  value: {
+                    "room_id": "!abnjk1jdasj98:capuchins.com",
+                    "servers": [
+                      "capuchins.com",
+                      "matrix.org",
+                      "another.com"
+                    ]
+                  }
+        "400":
+          description: The given `roomAlias` is not a valid room alias.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Room alias invalid"
+                  }
+        "404":
+          description: There is no mapped room ID for this room alias.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Room alias #monkeys:matrix.org not found."
+                  }
+      tags:
+        - Room directory
+    delete:
+      summary: Remove a mapping of room alias to room ID.
+      description: |-
+        Remove a mapping of room alias to room ID.
+
+        Servers may choose to implement additional access control checks here, for instance that
+        room aliases can only be deleted by their creator or a server administrator.
+
+        **Note:**
+        Servers may choose to update the `alt_aliases` for the `m.room.canonical_alias`
+        state event in the room when an alias is removed. Servers which choose to update the
+        canonical alias event are recommended to, in addition to their other relevant permission
+        checks, delete the alias and return a successful response even if the user does not
+        have permission to update the `m.room.canonical_alias` event.
+      operationId: deleteRoomAlias
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomAlias
+          description: |
+            The room alias to remove. Its format is defined
+            [in the appendices](/appendices/#room-aliases).
+          required: true
+          example: "#monkeys:matrix.org"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The mapping was deleted.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "404":
+          description: There is no mapped room ID for this room alias.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Room alias #monkeys:example.org not found."
+                  }
+      tags:
+        - Room directory
+  "/rooms/{roomId}/aliases":
+    get:
+      summary: Get a list of local aliases on a given room.
+      description: |-
+        Get a list of aliases maintained by the local server for the
+        given room.
+
+        This endpoint can be called by users who are in the room (external
+        users receive an `M_FORBIDDEN` error response). If the room's
+        `m.room.history_visibility` maps to `world_readable`, any
+        user can call this endpoint.
+
+        Servers may choose to implement additional access control checks here,
+        such as allowing server administrators to view aliases regardless of
+        membership.
+
+        **Note:**
+        Clients are recommended not to display this list of aliases prominently
+        as they are not curated, unlike those listed in the `m.room.canonical_alias`
+        state event.
+      operationId: getLocalAliases
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room ID to find local aliases of.
+          required: true
+          example: "!abc123:example.org"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The list of local aliases for the room.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  aliases:
+                    type: array
+                    description: The server's local aliases on the room. Can be empty.
+                    items:
+                      type: string
+                required:
+                  - aliases
+              examples:
+                response:
+                  value: {
+                    "aliases": [
+                      "#somewhere:example.com",
+                      "#another:example.com",
+                      "#hat_trick:example.com"
+                    ]
+                  }
+        "400":
+          description: The given `roomAlias` is not a valid room alias.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Room alias invalid"
+                  }
+        "403":
+          description: The user is not permitted to retrieve the list of local aliases for
+            the room.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not a member of the room."
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Room directory
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer