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

name: sh.tcp
version: "1.0"
title: 'SteelHead TCP General Setting Service'
description: 'REST API for the tcp general setting service.'
defaultAuthorization: 'required'
$schema: 'http://support.riverbed.com/apis/service_def/2.2'
id: 'http://support.riverbed.com/apis/sh.tcp/1.0'
provider: 'riverbed'

###############################################################################
#
# Types
#
###############################################################################

types:
    cong_ctrl_algo:
        description: >
            'standard' - Standard TCP optimization (RFC compliant):
                It is a standard-based implementation of TCP(RFC 793)
                and is the default settings in the SteelHead appliance.
            'auto-detect' - TCP automatic detection:
                Automatically detects the optimal TCP configuration
                by using the same mode as the peer SteelHead appliance
                for inner connections.
                When both appliances select this mode the standard TCP
                optimization is used.
            'highspeed' - HighSpeed TCP optimization:
                It is efficient in long fat networks(LFNs) with large
                WAN circuits (50 Mbps and above) over long distances.
            'bandwidth-estimation' - TCP bandwidth estimation optimization:
                It uses an intelligent bandwidth estimation algorithm
                along with a modified slow-start algorithm to optimize
                performance in long lossy networks.
            'rtt-invariant' - TCP RTT invariant optimization(TCP Hybla):
                It copes with longer round trip(RTTs) in heterogenrous
                networks which incorporate a terrestrial or satellite
                radio link. It aims to solve RTT disparity problem by
                modifying the standard rules for the congestion window
                increase according to an analytical study.
            'skipware-per-connection' - SkipWare per-connection TCP optimization:
                This feature requires a SkipWare license. It applies
                TCP congestion control to SCPS-capable connections.
                This control uses a modified slow-start algorithm and
                a modified congestion-avoidance approach while
                remaining reasonably fair and friendly to other traffic.
                This is a high-performance option for satellite networks.
            'skipware-error-tolerant' - SkipWare error tolerant TCP optimization:
                This feature requires a SkipWare license. It enables
                SkipWare optimization with the error-rate detection
                and recovery mechanism on the SteelHead appliance. It
                allows the per-connection congestion control to
                tolerate some loss due to corrupted packets without
                redoing the throughput. This is a high-performance
                option for lossy satellite networks.
        type: string
        enum: [standard,
               auto-detect,
               highspeed,
               bandwidth-estimation,
               rtt-invariant,
               skipware-per-connection,
               skipware-error-tolerant]
        default: standard

    cong_ctrl_option:
        type: object
        additionalProperties: false
        properties:
            algo:
                $merge:
                    source: { $ref: '#/types/cong_ctrl_algo' }
                    with: { description: 'Congestion Control Algorithm Option' }
            for_scps:
                description: >
                    This flag indicates an option applicable for SCPS. Currently, the
                    following set of options are applicable:
                    standard,
                    highspeed,
                    bandwidth-estimation,
                    skipware-per-connection,
                    skipware-error-tolerant
                type: boolean

resources:
    cong_ctrl_options_available:
        description: >
            TCP congestion control mode selections:
            Retrieve applicable congestion control mode selections:
            When the SkipWare license is present,
            it returns [{'algo' : 'standard', 'for_scps' : true},
                        {'algo' : 'auto-detect', 'for_scps' : false},
                        {'algo' : 'highspeed', 'for_scps' : true},
                        {'algo' : 'bandwidth-estimation', 'for_scps' : true},
                        {'algo' : 'rtt-invariant', 'for_scps' : false},
                        {'algo' : 'skipware-per-connection', 'for_scps' : true},
                        {'algo' : 'skipware-error-tolerant', 'for_scps' : true}]
            When the SkipWare license is absent,
            it returns [{'algo' : 'standard', 'for_scps' : true},
                        {'algo' : 'auto-detect', 'for_scps' : false},
                        {'algo' : 'highspeed', 'for_scps' : true},
                        {'algo' : 'bandwidth-estimation', 'for_scps' : true},
                        {'algo' : 'rtt-invariant', 'for_scps' : false}]
        type: object
        additionalProperties: false
        properties:
            items:
                type: array
                items:
                    $ref: '#/types/cong_ctrl_option'
        links:
            self:
                path: '$/cong_ctrl_options_available'

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

    cong_ctrl:
        description: 'TCP congestion control settings'
        type: object
        additionalProperties: false
        properties:
            mode:
                $ref: '#/types/cong_ctrl_algo'
            # More parameters to come

        links:
            self:
                path: '$/cong_ctrl'

            get:
                description: 'Retrieve the TCP congestion control setting instance'
                method: GET
                response:
                    $ref: '#/resources/cong_ctrl'

            set:
                description: 'Update the TCP congestion control setting instance'
                method: PUT
                request:
                    $ref: '#/resources/cong_ctrl'
                response:
                    $ref: '#/resources/cong_ctrl'

    rate_cap:
        description: >
            Impose a global data-transmit limit on the link rate for all SCPS
            connections between peer SteelHeads, or on the link rate
            for a SteelHead paired with a third-party device running
            TCP performance-enhancing proxies (TCP-PEP).
        type: object
        additionalProperties: false
        properties:
            enabled:
                type: boolean

        links:
            self:
                path: '$/rate_cap'

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

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

    satellite_option:
        description: 'Satellite communication option settings'
        type: object
        additionalProperties: false
        properties:
            sei_enabled:
                description: >
                    Enable/Disable transport optimization for single-end
                    interception connections with no SteelHead peer.
                type: boolean
                default: false

            legacy_compression_enabled:
                description: 'Enable/Disable SkipWare legacy compression'
                type: boolean
                default: false
            # More parameters to come

        links:
            self:
                path: '$/satellite_option'

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

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