# (C) Copyright 2014 Riverbed Technology, Inc.
# All rights reserved.

name: cmc.appstats
version: '1.0'
title: 'SteelCentral Controller Application Statistics Service'
description: >
    REST API for SteelCentral Controller Application Statistics Service
$schema: 'http://support.riverbed.com/apis/service_def/2.2'
id: 'http://support.riverbed.com/apis/cmc.appstats/1.0'
provider: 'riverbed'
#documentationLink:

types:
    serial:
        type: string
        description: 'The serial number of the appliance'
        pattern: '^[A-Za-z][0-9A-Fa-f]{2}[A-Za-z]{0,2}[0-9A-Fa-f]{8}$'

    protocol_id:
        type: integer
        description: 'The numeric Vineyard ID for a protocol'

    traffic_type:
        type: string
        description: 'The traffic type desired.'
        enum: ['any', 'optimized', 'passthrough']
        tags: {relint-disable: ['C0002']}

    byte_rate:
        type: number
        minimum: 0.0
        description: 'Bytes per second'

    byte_rate_series:
        type: array
        description: >
            Time series of byte rate values.
        items:
            description: >
                The byte rate value.
            oneOf:
                - $ref: '#/types/byte_rate'
                - type: 'null'
                  description: >
                      A value can be missing in which case the element is
                      type null.

    identifier:
        type: integer
        description: 'A unique identifier'

resources:

    application_byte_rates:
        type: object
        description: >
            Get the byte rates for the given protocols and sites.
        additionalProperties: false

        properties:
            start_time:
                description: 'Unix epoch timestamp.'
                type: integer
            end_time:
                description: 'Unix epoch timestamp.'
                type: integer
            resolution:
                description: >
                    The resolution in which the statistics samples have to be
                    returned.
                type: integer
            traffic_type: {$ref: '#/types/traffic_type'}
            protocols:
                type: array
                description: >
                    List of Layer7 protocol IDs. If this property is not present
                    then it means the data is for all protocols.
                items:
                    $ref: '#/types/protocol_id'
            site_ids:
                type: array
                description: >
                    List of site IDs. If this property is not present then it
                    means the data is for all sites.
                items:
                    description: 'The Site ID value.'
                    type: integer
            wan_inbound:
                $merge:
                    source: { $ref: '#/types/byte_rate_series' }
                    with: { description: 'WAN Inbound byte rates' }
            wan_outbound:
                $merge:
                    source: { $ref: '#/types/byte_rate_series' }
                    with: { description: 'WAN Outbound byte rates' }
            lan_inbound:
                $merge:
                    source: { $ref: '#/types/byte_rate_series' }
                    with: { description: 'LAN Inbound byte rates' }
            lan_outbound:
                $merge:
                    source: { $ref: '#/types/byte_rate_series' }
                    with: { description: 'LAN Outbound byte rates' }
        required: [start_time, end_time, resolution, traffic_type, wan_inbound, 
            wan_outbound, lan_inbound, lan_outbound]

        links:
            self:
                path: '$/reports/application_byte_rates'
                params:
                    start_time:
                        type: integer
                        description: >
                            This is a required filter. Not specifying this value
                            will result in an error.
                    end_time:
                        type: integer
                        description: >
                            This is a required filter. Not specifying this value
                            will result in an error.
                    resolution:
                        type: integer
                        description: >
                            If present and nonzero this specifies the resolution
                            desired. Otherwise, statistics are returned for the 
                            finest resolution available for the whole time range. 
                            Coarser resolutions are retained longer.
                    traffic_type:
                        $merge:
                            source: {$ref: '#/types/traffic_type'}
                            with:
                                description: >
                                    If not specified, it assumed to be 'any'.
                    protocols:
                        type: string
                        description: >
                            Comma separated list of protocols. If not specified
                            data is returned for all protocols.
                    site_ids:
                        type: string
                        description: >
                            Comma separated list of site IDs. If not specified
                            data is returned for all sites.

            get:
                method: GET
                response:
                    $ref: '#/resources/application_byte_rates'

    top_applications:
        type: object
        description: >
            The top N applications ordered by WAN average for the given
            traffic_type and time range.
        additionalProperties: false

        properties:
            start_time:
                description: 'Unix epoch timestamp.'
                type: integer
            end_time:
                description: 'Unix epoch timestamp.'
                type: integer
            resolution:
                description: >
                    The resolution in which the statistics samples have to be
                    returned.
                type: integer
            traffic_type: {$ref: '#/types/traffic_type'}
            limit:
                type: integer
                minimum: 1
                description: >
                    The limit specifying the 'N' value for top N applications.

            # This is the 'top_applications' key in the response object.
            # This contains the actual response with an array of top N
            # applications
            top_applications:
                type: array
                description: >
                    The list of top N applications.
                items:
                    description: >
                        Each item is an object describing a protocol and it's
                        corresponding statistics.
                    type: object
                    additionalProperties: false
                    properties:
                        protocol_id:
                            $merge:
                                source: {$ref: '#/types/protocol_id'}
                                with: {description: 'L7 protocol id'}
                        wan_avg:
                            $merge:
                                source: {$ref: '#/types/byte_rate'}
                                with:
                                    description: >
                                        Average WAN byte rates corresponding to
                                        the protocol_id in this item. The
                                        average is calculated after combining
                                        wan_inbound and wan_outbound byte
                                        rates.
                    # required list for items in top_applications array
                    required: [protocol_id, wan_avg]

        # required list for the entire resource object
        required: [start_time, end_time, resolution, traffic_type, limit, 
            top_applications]

        links:
            self:
                path: '$/reports/top_applications'
                params:
                    start_time:
                        type: integer
                        description: >
                            This is a required filter. Not specifying this will
                            result in an error.
                    end_time:
                        type: integer
                        description: >
                            This is a required filter. Not specifying this will
                            result in an error.
                    resolution:
                        type: integer
                        description: >
                            If present and nonzero this specifies the resolution
                            desired. Otherwise, statistics are returned for the 
                            finest resolution available for the whole time range.
                            Coarser resolutions are retained longer.
                    traffic_type:
                        $merge:
                            source: {$ref: '#/types/traffic_type'}
                            with:
                                description: >
                                    If not specified, it assumed to be 'any'
                    limit:
                        type: integer
                        minimum: 1
                        description: >
                            If not specified it is assumed to be 10.
                    site_id:
                        type: integer
                        description: >
                            If a site_id is specified, the top N applications
                            are calculated and returned for that particular
                            site. If not specified, the top applications are
                            calculated across all sites.

            get:
                method: GET
                response:
                    $ref: '#/resources/top_applications'

    global_config:
        description: "Global application statistics configuration"
        type: object
        additionalProperties: False
        required: [enabled]
        properties:
            enabled:
                type: boolean
                description: "Enable application statistics collection"
        links:
            self:
                path: "$/global_config"
            get:
                method: GET
                response:
                    $ref: '#/resources/global_config'
            set:
                method: PUT
                request:
                    $ref: '#/resources/global_config'
                response:
                    $ref: '#/resources/global_config'

    site_configs:
        description: "List of site_configs"
        type: array
        tags: {relint-disable: ['C0301']}
        items:
            $merge:
                source: { $ref: '#/resources/site_config'}
                with:
                    relations:
                        full:
                            description: >
                                Relation to the site_config resource
                                coresponding to this item.
                            resource: '#/resources/site_config'
                            vars: {id: "0/id"}
        links:
            self:
                path: "$/site_configs"
            create:
                method: POST
                request:
                    $ref: '#/resources/site_config'
                response:
                    $ref: '#/resources/site_config'

            get:
                method: GET
                response:
                    $ref: '#/resources/site_configs'

    site_config:
        tags: {relint-disable: ['W0005']}  # FIXME: later
        description: "Site specific application statistics configuration"
        type: object
        additionalProperties: false
        required: [enabled]
        properties:
            id:
                $merge:
                    source: { $ref: '#/types/identifier' }
                    with: { readOnly: true }
            site_id:
                type: integer
                description: "Site ID"
            site_type_id:
                type: integer
                description: "Site type ID"
            enabled:
                type: boolean
                description: "Enable application statistics"
        oneOf:
            - type: object
              required: [site_id]
              tags: {relint-disable: ['C0200']}
            - type: object
              required: [site_type_id]
              tags: {relint-disable: ['C0200']}

        relations:
            instances:
                description: >
                    All instances of site configurations.
                resource: '#/resources/site_configs'

        links:
            self:
                path: "$/site_configs/items/{id}"

            get:
                method: GET
                response:
                    $ref: '#/resources/site_config'

            set:
                method: PUT
                request:
                    $ref: '#/resources/site_config'
                response:
                    $ref: '#/resources/site_config'

            delete:
                method: DELETE