swagger: "2.0"
info:
    title: Watchman service
    description: |-
        Watchman collects media playback reports.
        		Playback time along with buffering count and duration is collected
        		via playback reports, which should be sent from the client each n sec
        		(with n being something reasonable between 5 and 30s)
        	
    version: 0.0.1
host: watchman.na-backend.odysee.com
consumes:
    - application/json
    - application/xml
    - application/gob
produces:
    - application/json
    - application/xml
    - application/gob
paths:
    /healthz:
        get:
            tags:
                - reporter
            summary: healthz reporter
            operationId: reporter#healthz
            responses:
                "200":
                    description: OK response.
                    schema:
                        type: string
            schemes:
                - https
    /reports/playback:
        post:
            tags:
                - reporter
            summary: add reporter
            operationId: reporter#add
            parameters:
                - name: AddRequestBody
                  in: body
                  required: true
                  schema:
                    $ref: '#/definitions/PlaybackReport'
                    required:
                        - url
                        - duration
                        - position
                        - rel_position
                        - rebuf_count
                        - rebuf_duration
                        - protocol
                        - player
                        - user_id
                        - device
            responses:
                "201":
                    description: Created response.
                "400":
                    description: Bad Request response.
                    schema:
                        $ref: '#/definitions/MultiFieldError'
                        required:
                            - message
            schemes:
                - https
definitions:
    MultiFieldError:
        title: MultiFieldError
        type: object
        properties:
            message:
                type: string
                example: rebufferung duration cannot be larger than duration
        example:
            message: rebufferung duration cannot be larger than duration
        required:
            - message
    PlaybackReport:
        title: PlaybackReport
        type: object
        properties:
            bandwidth:
                type: integer
                description: Client bandwidth, bit/s
                example: 1850104351
                format: int32
            bitrate:
                type: integer
                description: Media bitrate, bit/s
                example: 611106208
                format: int32
            cache:
                type: string
                description: Cache status of video
                example: local
                enum:
                    - local
                    - player
                    - miss
            device:
                type: string
                description: Client device
                example: web
                enum:
                    - ios
                    - adr
                    - web
                    - dsk
                    - stb
            duration:
                type: integer
                description: Duration of time between event calls in ms (aiming for between 5s and 30s so generally 5000–30000)
                example: 30000
                format: int32
                minimum: 0
                maximum: 60000
            player:
                type: string
                description: Player server name
                example: sg-p2
                maxLength: 128
            position:
                type: integer
                description: Current playback report stream position, ms
                example: 2068464011
                format: int32
                minimum: 0
            protocol:
                type: string
                description: Standard binary stream (`stb`), HLS (`hls`) or live stream (`lvs`)
                example: stb
                enum:
                    - stb
                    - hls
                    - lvs
            rebuf_count:
                type: integer
                description: Rebuffering events count during the interval
                example: 108657605
                format: int32
                minimum: 0
            rebuf_duration:
                type: integer
                description: Sum of total rebuffering events duration in the interval, ms
                example: 52192
                format: int32
                minimum: 0
                maximum: 60000
            rel_position:
                type: integer
                description: Relative stream position, pct, 0—100
                example: 99
                format: int32
                minimum: 0
                maximum: 100
            url:
                type: string
                description: LBRY URL (lbry://... without the protocol part)
                example: '@veritasium#f/driverless-cars-are-already-here#1'
                maxLength: 512
            user_id:
                type: string
                description: User ID
                example: "432521"
                minLength: 1
                maxLength: 45
        example:
            bandwidth: 1124249943
            bitrate: 1825042135
            cache: player
            device: adr
            duration: 30000
            player: sg-p2
            position: 1501556176
            protocol: lvs
            rebuf_count: 1077102125
            rebuf_duration: 47972
            rel_position: 14
            url: '@veritasium#f/driverless-cars-are-already-here#1'
            user_id: "432521"
        required:
            - url
            - duration
            - position
            - rel_position
            - rebuf_count
            - rebuf_duration
            - protocol
            - player
            - user_id
            - device