swagger: "2.0"
info:
  version: "2.0.0"
  title: Smartphone Test Farm
  description: Control and manager real Smartphone devices from browser and restful apis
  license:
    name: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: STF Support
    email: contact@openstf.io
    url: http://openstf.io/
basePath: /api/v1
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
tags:
  - name: user
    description: User Operations
  - name: device
    description: Device Operations
paths:
  /user:
    x-swagger-router-controller: user
    get:
      summary: User Profile
      description: The User Profile endpoint returns information about current authorized user.
      operationId: getCurrentUser
      tags:
        - user
      responses:
        "200":
          description: Current User Profile information
          schema:
            $ref: "#/definitions/UserResponse"
        default:
          description: Unexpected Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      security:
        - accessTokenAuth: []
  /user/devices:
    x-swagger-router-controller: user
    get:
      summary: List devices owned by current user
      description: The User Devices endpoint returns information about user group of current authorized user.
      operationId: getCurrentUserDevices
      tags:
        - user
      responses:
        "200":
          description: Current User Devices information
          schema:
            $ref: "#/definitions/DeviceListResponse"
        default:
          description: Unexpected Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      security:
        - accessTokenAuth: []
    post:
      summary: Add device to a user
      description: The User Devices endpoint will request stf server for a new device. It will return request accepted if device is usable.
      operationId: addDeviceToUser
      tags:
        - user
      parameters:
        - name: device
          in: body
          description: Device to add
          required: true
          schema:
            $ref: "#/definitions/DeviceAddPayload"
      responses:
        "202":
          description: Device Add Request Status
        default:
          description: Unexpected Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      security:
        - accessTokenAuth: []
  /user/devices/{serial}:
    x-swagger-router-controller: user
    delete:
      summary: Release device from user
      description: The User Devices endpoint will request for device release from stf server.
      operationId: deleteDeviceFromUser
      tags:
        - user
      parameters:
        - name: serial
          in: path
          description: Device Serial
          required: true
          type: string
      responses:
        "202":
          description: Device Release Request Status
        default:
          description: Unexpected Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      security:
        - accessTokenAuth: []
  /user/accessTokens:
    x-swagger-router-controller: token
    get:
      summary: Access Tokens
      description: The Access Tokens endpoints returns titles of all the valid access tokens.
      operationId: getAccessTokens
      tags:
        - user
      responses:
        "200":
          description: Access Tokens titles
          schema:
            $ref: "#/definitions/AccessTokensResponse"
        default:
          description: Unexpected Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      security:
        - accessTokenAuth: []
  /devices:
    x-swagger-router-controller: device
    get:
      summary: Device List
      description: The devices enpoint return list of all the STF devices including Disconnected and Offline
      operationId: getDevices
      tags:
        - device
      responses:
        "200":
          description: List of Devices
          schema:
            $ref: "#/definitions/DeviceListResponse"
        default:
          description: Unexpected Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      security:
        - accessTokenAuth: []
  /devices/{serial}:
    x-swagger-router-controller: device
    get:
      summary: Device Information
      description: The device enpoint return information about a single device.
      operationId: getDeviceBySerial
      tags:
        - device
      parameters:
        - name: serial
          in: path
          description: Device Serial
          required: true
          type: string
        - name: fields
          in: query
          description: Fields query parameter takes a comma seperated list of fields. Only listed field will be return in response
          required: false
          type: string
      responses:
        "200":
          description: Device Information
          schema:
            $ref: "#/definitions/DeviceResponse"
        default:
          description: Unexpected Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      security:
        - accessTokenAuth: []
  /swagger.json:
    x-swagger-pipe: swagger_raw
definitions:
  UserResponse:
    required:
      - user
    properties:
      user:
        type: object
  AccessTokensResponse:
    required:
      - tokens
    properties:
      tokens:
        type: array
        items:
          type: string
  DeviceListResponse:
    required:
      - devices
    properties:
      devices:
        type: array
        items:
          type: object
  DeviceResponse:
    required:
      - device
    properties:
      device:
        type: object
  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: string
  DeviceAddPayload:
    description: payload object for adding device to user
    required:
      - serial
    properties:
      serial:
        description: Device Serial
        type: string
      timeout:
        description: Device timeout in ms. If device is kept idle for this period, it will be automatically disconnected. Default is provider group timeout.
        type: integer

securityDefinitions:
  accessTokenAuth:
    type: apiKey
    name: accessTokenAuth
    in: header