$schema: 'http://support.riverbed.com/apis/service_def/2.2'
id: 'http://support.riverbed.com/apis/cmc.sectransport/2.0'
provider: 'riverbed'
name: cmc.sectransport
version: "2.0"
title: REST API for secure transport managment
description: REST API for Secure Transport service

types:
  ###################################################################################
  # Security Group Member
  ###################################################################################
  # Defines a member of a group, typed to facilitate format checking
    serial:
        type: string
        description: Universally unique ID for an appliance
 
    ipv4address:
        description: IPv4 address (x.y.z.k)
        type: string
        pattern: '^((?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))?$'
 
    stat_block:
        type: object
        description: Representation of a statistics object
        properties:
            bytes_in:
                description: 'Bytes received'
                type: number
                readOnly: true
            bytes_out:
                description: 'Bytes sent'
                type: number
                readOnly: true
            packets_in:
                description: 'Packets received'
                type: number
                readOnly: true
            packets_out:
                description: 'Packets sent'
                type: number
                readOnly: true
        additionalProperties: false
 
 
    datapoint:
        type: object
        description: Representation of a datapoints object
        additionalProperties: false
        properties:
            timestamp: {type: integer, description: Timestamp of datapoint}
            data:
                $ref: '#/types/stat_block'
 
 
    peer_stats:
        type: object
        description: Representation of a peer statistics object
        additionalProperties: false
        properties:
            serial:
                $merge:
                    source: { $ref: '#/types/serial' }
                    with: { description: Peer(appliance) for which this resource represents the stats }
            stats:
                type: array
                description: Array of datapoints
                items:
                    $ref: '#/types/datapoint'
            rekey_times:
                type: array
                description: List of rekey timestamps
                items:
                    description: Timestamp of rekey
                    type: integer

resources:
    peer_group_stats:
        $merge:
            source: { $ref: '#/types/peer_stats' }
            with:
                required: [ serial ]
                description: Group-level stats for this peer relative to other peers in the group
    
                links:
                    self:
                        path: $/appliances/items/{serial}/group_stats
                        params:
                            group_id: {type: integer, description: Id of group}
                            start_time: {type: integer, description: Group statistics start time}
                            end_time:  {type: integer, description: Group statistics end time}
                    get:
                        method: GET
                        response:
                            $ref: '#/resources/peer_group_stats'
  
    all_peer_group_stats:
        type: object
        description: Peer group statistics for all peers belonging to a group
        additionalProperties: false
        properties:
            id:
                type: integer
                description: Group Id for which this resource represents the stats
            peer_stats:
                type: array
                description: Array of peer statistics
                items:
                    $ref: '#/types/peer_stats'
        links:
            self:
                path: $/groups/items/{id}/all_peer_group_stats
                params:
                    start_time: {type: integer, description: All peer group statistics start time}
                    end_time:  {type: integer, description: All peer group statistics end time}
            get:
                method: GET
                response:
                    $ref: '#/resources/all_peer_group_stats'

    group_stats:
        type: object
        description: Group-level stats
        additionalProperties: false
        properties:
            id:
                type: integer
                description: Group Id for which this resource represents the stats
            stats:
                type: array
                description: Array of datapoints
                items:
                    $ref: '#/types/datapoint'
            rekey_times:
                type: array
                description: List of rekey timestamps
                items:
                    type: integer
                    description: Rekey timestamp
        links:
            self:
                path: $/groups/items/{id}/group_stats
                params:
                    start_time: {type: integer, description: Group statistics start time}
                    end_time:  {type: integer, description: Group statistics end time}
            get:
                method: GET
                response:
                    $ref: '#/resources/group_stats'


    #############################################################################
    # Appliance information
    #############################################################################
    # Defines an appliance and its relationships in ST
    appliance:
        type: object
        description: Registered appliance
        additionalProperties: false
        properties:
            id:
                type: integer
                description: Appliance inventory id

            serial:
                $merge:
                    source: { $ref: '#/types/serial' }
                    with: { description: Universally Unique Identifier }

            name:
                type: string
                description: The human readable name of the appliance

            group_membership:
                type: array
                description: What security groups this appliance belongs to
                items:
                    type: integer
                    description: Group membership Id
                    relations:
                        full:
                            resource: '#/resources/group'
                            description: Group resource
                            vars:
                                id: "0"

        links:
            self:
                path: "$/appliances/items/{serial}"

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


        relations:
            instances:
                resource: '#/resources/appliances'
                description: Appliances resource

            group_stats:
                resource: '#/resources/peer_group_stats'
                description: Peer group statistics resource
                vars: {serial: "0/serial"}


    ###################################################################################
    # Appliance information
    ###################################################################################
    # When the controller starts up, it needs to get all the info at once with this
    appliances:
        type: object
        description: ST information for all registered appliances on the system
        additionalProperties: false
        properties:
            items:
                type: array
                description: List of registered appliances
                items:
                    $merge:
                        source: { $ref: '#/resources/appliance' }
                        with:
                            relations:
                                full:
                                    resource: '#/resources/appliance'
                                    description: Appliance resource
                                    vars:
                                        serial: "0/serial"

        links:
            self:
                path: "$/appliances"

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


    #############################################################################
    # Security Group
    #############################################################################


    # This defines a group for individual queries
    group:
        type: object
        description: A secure transport group
        additionalProperties: True
        required: [ name ]
        properties:
            # This is the unique identifier
            id:
                type: integer
                description: Permanent ID of the group
                readOnly: True

            name:
                type: string
                description: Name of the group
                readOnly: True

            key_auto_expiry:
                type: number
                description: Max time in seconds that a key can be used
                minimum: 31
                maximum: 31557600

            data_rekey_volume:
                # This property needs a better name...
                type: number
                description: Max number of bytes that can be transfered in a security group before rekey
                minimum: 0

            rekey_pktprcnt:
                type: number
                description: Percentage of packets from max, when re-key must be performed
                minimum: 0
                maximum: 100

            rekey_pktcnt:
                type: integer
                description: Cumulative packet counter for a SPI, after which re-key must be performed
                minimum: 0

            headless_timeout:
                type: number
                description: How long in seconds can an appliance run without controller link
                minimum: 31
                maximum: 31557600

            keepalive_interval:
                type: integer
                description: How often should keep alive messages be sent between peers
                minimum: 10
                maximum: 3600

            # Group membership
            members:
                type: array
                description: The members of this security group
                items:
                    type: object
                    description: The member of this security group
                    additionalProperties: false
                    properties:
                        serial:
                            $ref: '#/types/serial'
                        name:
                            type: string
                            description: The member name of this security group
                    readOnly: true
                    relations:
                        full:
                            resource: '#/resources/appliance'
                            description: Appliance resource
                            vars:
                                serial: "0/serial"

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

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

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

        relations:
            instances:
                description: Groups resource
                resource: '#/resources/groups'

            group_stats:
                description: Groups statistics resource
                resource: '#/resources/group_stats'
                vars: {id: "0/id"}


    ###################################################################################
    # Security Group
    ###################################################################################
    # Collection of all group resources
    groups:
        type: object
        description: All of the groups configured in the system
        additionalProperties: false
        properties:
            items:
                type: array
                description: List of groups configured
                items:
                    $merge:
                        source: { $ref: '#/resources/group' }
                        with:
                            relations:
                                full:
                                    resource: '#/resources/group'
                                    description: Groups resource
                                    vars:
                                        id: "0/id"
        links:
            self:
                path: "$/groups"

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


    ###################################################################################
    # Security Group
    ###################################################################################
    # When the controller starts up, it needs to get all the info at once with this
    configuration:
        type: object
        description: Secure Transport Configuration
        additionalProperties: false
        properties:
            groups:
                $merge:
                    source: { $ref: '#/resources/groups' }
                    with: { description: All the groups configured in the system }
            revision:
                type: string
                description: Revision of this configuration

        links:
            self:
                path: "$/configuration"

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

    poller:
        type: object
        description: Temporary callback for stats poll requests
        additionalProperties: false
        required: [ poll_req_id, serial, poll_time, resp_data ]
        properties:
            poll_req_id:
                type: integer
                description: Request id registered with poller
            serial:
                type: string
                description: Appliance from which response is received
            poll_time:
                description: Appliance poll time
                type: integer
            resp_data:
                type: string
                description: Response from the polled request

        links:
            self:
                path: "$/poller_callback"

            callback:
                method: POST
                description: Callback to get polled response
                request:
                    $ref: '#/resources/poller'