# (C) Copyright 2014 Riverbed Technology, Inc.
# All rights reserved.
$schema: 'http://support.riverbed.com/apis/service_def/2.2'
id: 'http://support.riverbed.com/apis/mgmt.newsfeeds/1.0'
provider: 'riverbed'
name: mgmt.newsfeeds
version: "1.0"
title: News feed service
description: REST API for News Feed Service
defaultAuthorization: none

types:
    news_resource:
        description: >
            Contains JSON data supporting the news.
            It should be self describing, containing information to interpret
            the JSON data.
        type: object
        properties:
            resource_id:
                description: ID of the schema containing resource
                type: string
            json_object:
                type: object
                additionalProperties: true
                description: >
                    Object containing details of the news feed item:
                    contains new object for configuration type,
                    contains event object if based on lumberjack events framework.
            object_tag:
                type: string
                description: Tag for the JSON resource
        additionalProperties: false
        required: [ resource_id, object_tag, json_object]

    news_resources:
        description: Additional detailed information about the news
        type: object
        properties:
            items:
                type: array
                items: { $ref: '#/types/news_resource' }

resources:
    feeds:
        description: List of available feeds
        type: object
        properties:
            items:
                type: array
                items:
                    $ref: '#/resources/feed'
        links:
            self: { path: '$/feeds'}
            get:
                method: GET
                response: {$ref: '#/resources/feeds' }


    feed:
        description: >
            Provides information about the feed. Also gives
            the categories and ID's for what news can be posted.
        type: object
        additionalProperties: false
        properties:
            name:
                type: string
                description: Name of the feed
            categories:
                description: Feed categories
                type: array
                items:
                    type: object
                    properties:
                        name:
                            type: string
                        items:
                            type: array
                            items:
                                $ref: '#/resources/summary'
        links:
            self: { path: '$/feeds/items/{name}' }
            get:
                method: GET
                response: { $ref: '#/resources/feed' }


    summary:
        description: Describes the feed
        type: object
        properties:
            id:
                type: string
                description: Unique summary ID
            summary:
                type: string
                description: Brief user visible summary of the description

        links:
            self: { path: '$/feeds/items/{name}/items/{id}' }
            get:
                method: GET
                response: { $ref: '#/resources/summary' }


    news:
        description: >
            A collection of all news on the system. It
            supports various query parameters for getting news. New news can
            be posted here.
        type: object
        properties:
            items:
                type: array
                items: {$ref: '#/resources/news_item' }
        links:
            self:
                path: "$/news"
                description: >
                    Multiple serach parameters can be used.
                    Default parameters are limit=50&offset=0
                params:
                    feed_id: { type: string }
                    feed_name: { type: string }
                    feed_category: { type: string }
                    user: { type: string }
                    remote_user: { type: string }
                    audit_id: { type: string }
                    source: { type: string }
                    severity: { type: string }
                    start_time: { type: timestamp-hp }
                    end_time: { type: timestamp-hp }
                    #
                    # 100 might be less when cmc polls, so default to 100
                    # but allow a max of 1000
                    limit:
                        type: integer
                        default: 100
                        maximum: 1000
                        minimum: 1
                    offset: { type: integer }
            get:
                method: GET
                response: {$ref: '#/resources/news' }
            create:
                method: POST
                request: {$ref: '#/resources/news_item' }
                response: {$ref: '#/resources/news_item' }
            set:
                method: PUT
                request: {$ref: '#/resources/news' }
                response: {$ref: '#/resources/news' }

    news_item:
        type: object
        description: The schema for news items
        additionalProperties: false
        properties:
            id:
                type: integer
                description: ID of the news item
                readOnly: true
            timestamp:
                type: timestamp-hp
                description: Miliseconds since epoch of news feed item
            feed_name:
                type: string
                description: Name of the feed
            feed_category:
                description: Category of the feed
                type: string
            feed_id:
                type: string
                description: Registered feed identification tag
            user:
                type: string
                description: >
                    Username for user driven feeds. Defaults to
                    Blank for nonuser driven feeds."
            remote_user:
                type: string
                description: >
                    Remote username for user driven feeds. This can be the SCC
                    user or the user authenticated through TACACs.
                    Defaults to Blank for nonuser driven feeds."
            audit_id:
                type: string  # This is based on what aaa decides to provide
                description: >
                    An audit itentification ID to tag related resources
                    together. Blank string if none.
            source:
                type: string
                description: Service sending out the news feed item
            severity:
                type: string
                description: Severity of the news feed item
                enum: ['low', 'normal', 'high', 'critical']
            details:
                type: string
                description: Detailed description of news feed item
            resources: {$ref: '#/types/news_resources' }
        required: [feed_id, feed_name, feed_category, timestamp, severity,
            user, remote_user, audit_id, source, details]

        relations:
            feed:
                resource: '#/resources/feed'
                vars:
                    name: '0/feed_name'
            summary:
                resource: '#/resources/summary'
                vars:
                    name: '0/feed_name'
                    id: '0/feed_id'
            instances:
                resource: '#/resources/news'

        links:
            self: { path: '$/news/items/{id}'}
            get:
                method: GET
                response: {$ref: '#/resources/news_item' }
