$schema: 'http://support.riverbed.com/apis/service_def/2.2'
id: 'http://support.riverbed.com/apis/cmc.configurator/1.1'
provider: 'riverbed'
name: "cmc.configurator"
version: "1.1"
title: "REST API for Configurator"

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

types:

    job_status:
        type: string
        description: The status of the job
        enum: ['Queued', 'InProgress', 'Failed', 'Success', 'Canceled']
        readOnly: true

    interpreter_job_status:
        type: string
        description: The status of the job submitted to the interpreter
        enum: ['Pending', 'Running', 'Completed']
        readOnly: true

    interpreter_job_result:
        type: string
        description: the result of the job submitted to the interpreter
        enum: ['Fail', 'Success']
        readOnly: true

###############################################################################
#
# Define the REST API
#
###############################################################################

resources:

    jobs:
        description: All scheduled/inprogress/completed job list.
        type: array
        items:
            $ref: '#/resources/job'

        links:
            self:
                path: "$/jobs"
                # Allow filtering on the status
                params:
                    # If multiple query params are passed then the result would be an 
                    # "AND" of all the conditions.
                    # (job_status) & (feature_ids) & (after) & (before)
                    # This could be a  comma seperated string.
                    job_status:
                        type: string
                        description: This is the list of all jobs. The jobs can be comma seperated.
                    # This could be a comma seperated string.
                    feature_id:
                        type: integer
                        description: This is the feature IDs to be queried on.The feature IDs can be comma seperated.
                    after:
                        # This is the value in seconds (epoch)on or after which you want the jobs listed.
                        description: Give all jobs after.
                        type: integer
                    before:
                        # This is the value in seconds (epoch)on or before which you want the jobs listed.
                        description: Give all jobs before.
                        type: integer

            get:
                description: Retrieve all push config job details.
                method: GET
                response:
                    $ref: '#/resources/jobs'

            create:
                description: Schedule a push config job.
                method: POST
                request:
                    $ref: '#/resources/job'
                response:
                    $ref: '#/resources/job'



    job:
        description: Job Scheduling resource.
        type: object
        properties:
            id:
                type: integer
                readOnly: true
            site_ids:
                description: Array of site IDs.
                type: array
                minItems: 1
                items:
                    type: integer
            appliance_serial_numbers:
                description: Array of appliance serial number.
                type: array
                minItems: 1
                items:
                    type: string
            operation:
                type: string
            idx:
                type: integer
            timestamp:
                type: integer
            site_type_ids:
                description: Array of site types to push onto.
                type: array
                minItems: 1
                items:
                    type: integer
            feature_ids:
                description: Array of feature IDs.
                type: array
                minItems: 1
                items:
                    type: integer
            creation_time:
                description: Creation time of the job.
                type: integer
                readOnly: true
            push_time:
                description: Push time of the job. This will be present for jobs whose state is one of 'IN_PROGRESS', 'FAILED', 'SUCCESS'
                anyOf:
                   - type: integer
                     readOnly: true
                   - type: "null"
            completion_time:
                description: Completion time of the job.
                anyOf:
                   - type: integer
                     readOnly: true
                   - type: "null"
            error_text:
                description: Error text if pre push failed. Key needs to be checked if it exist before you try to access it.
                anyOf:
                   - type: string
                     readOnly: true
                   - type: "null"
            job_status:
                $merge:
                    source: { $ref: '#/types/job_status' }
                    with: { description: Status of the submitted job. }
            backup:
                description : Flag to indicate if the user wants to take a back up or not.
                type: boolean
            detailed_status:
                type: array
                readOnly: true
                items:
                    type: object
                    readOnly: true
                    additionalProperties: false
                    properties:
                        feature_id:
                            type: integer
                        status:
                            $ref: '#/types/interpreter_job_status'
                        serialnum:
                            type: string
                        result:
                            $ref: '#/types/interpreter_job_result'
                        error_text:
                            description: Error text if push pushed for a particular feature.
                            anyOf:
                               - type: string
                                 readOnly: true
                               - type: "null"

        additionalProperties: false
        required: [feature_ids]
        # Additional validation criteria.
        oneOf:
            - type: object
              required: [site_ids]
            - type: object
              required: [appliance_serial_numbers]
            - type: object
              required: [site_type_ids]

        relations:
            instances:
                resource: '#/resources/jobs'

        links:
            self:
                description: Base URI for job in a queue
                path: "$/jobs/items/{id}"

            get:
                description: Retrieve a push config job deatils
                method: GET
                response:
                    $ref: '#/resources/job'

            cancel:
                path: "$/jobs/items/{id}/cancel"
                description: Cancel a push config job details
                method: POST
                response:
                    $ref: '#/resources/job'


    feature:
        description: Resource to get a particular feature.
        type: object
        additionalProperties: false
        required: [push_enable]
        properties:
            id:
                type: integer
                readOnly: true
            name:
                description: Name of the feature.
                type: string
                readOnly: true
            pretty_name:
                description: Pretty name of the feature.
                type: string
                readOnly: true
            description:
                description: Description of the feature.
                type: string
                readOnly: true
            push_enable:
                description: Feature push enable/disable flag.
                type: boolean
            parent:
                description: Parent ID of the feature.
                type: integer
                readOnly: true
            children:
                description: Name and ID of sub features.
                type: array
                readOnly: true
                items:
                    type: object
                    additionalProperties: false
                    properties:
                        id:
                            type: integer
                            readOnly: true
                        name:
                            type: string
                            readOnly: true

        links:
            self:
                description: Base URI for getting information about a feature.
                path: "$/features/items/{id}"
            get:
                description: Retrieve the feature specific information.
                method: GET
                response:
                    $ref: '#/resources/feature'

            set:
                description: Set a specific feature.
                method: PUT
                request:
                    $ref: '#/resources/feature'
                response:
                    $ref: '#/resources/feature'

    features:
        description: Resource to get the features supported.
        type: array
        items:
            $ref: '#/resources/feature'

        links:
            self:
                description: Base URI for feature supported
                path: "$/features"
                params:
                    name:
                        type: string
            get:
                description: Retrieve the features supported for push.
                method: GET
                response:
                    $ref: '#/resources/features'


