# 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 device management API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/devices":
    get:
      summary: List registered devices for the current user
      description: |-
        Gets information about all devices for the current user.
      operationId: getDevices
      security:
        - accessToken: []
      responses:
        200:
          description: Device information
          schema:
            type: object
            properties:
              devices:
                type: array
                description: A list of all registered devices for this user.
                items:
                  type: object
                  allOf:
                    - $ref: "definitions/client_device.yaml"
          examples:
            application/json: {
                "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:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: deviceId
          description: The device to retrieve.
          required: true
          x-example: "QBUAZIFURK"
      responses:
        200:
          description: Device information
          schema:
            type: object
            allOf:
              - $ref: "definitions/client_device.yaml"
          examples:
            application/json: {
                "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: Update a device
      description: |-
        Updates the metadata on the given device.
      operationId: updateDevice
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: deviceId
          description: The device to update.
          required: true
          x-example: "QBUAZIFURK"
        - in: body
          name: body
          required: true
          description: New information for the device.
          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" }
      responses:
        200:
          description: The device was successfully updated.
          examples:
            application/json: {
              }
          schema:
            type: object  # empty json object
        404:
          description: The current user has no device with the given ID.
      tags:
        - Device management
    delete:
      summary: Delete a device
      description: |-
        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).

        Deletes the given device, and invalidates any access token associated with it.
      operationId: deleteDevice
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: deviceId
          description: The device to delete.
          required: true
          x-example: "QBUAZIFURK"
        - in: body
          name: body
          required: true
          schema:
            type: object
            properties:
              auth:
                description: |-
                  Additional authentication information for the
                  user-interactive authentication API.
                allOf:
                  - "$ref": "definitions/auth_data.yaml"
      responses:
        200:
          description: |-
            The device was successfully removed, or had been removed
            previously.
          schema:
            type: object
          examples:
            application/json: {
              }
        401:
          description: |-
            The homeserver requires additional authentication information.
          schema:
            "$ref": "definitions/auth_response.yaml"
      tags:
        - Device management
  "/delete_devices":
    post:
      summary: Bulk deletion of devices
      description: |-
        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).

        Deletes the given devices, and invalidates any access token associated with them.
      operationId: deleteDevices
      security:
        - accessToken: []
      parameters:
        - in: body
          name: body
          required: true
          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
      responses:
        200:
          description: |-
            The devices were successfully removed, or had been removed
            previously.
          schema:
            type: object
          examples:
            application/json: {
              }
        401:
          description: |-
            The homeserver requires additional authentication information.
          schema:
            "$ref": "definitions/auth_response.yaml"
      tags:
        - Device management