chronograf/swagger.yaml

swagger: '2.0'
info:
    title: Mr Fusion
    description: Fuel for Chronograf
    version: "1.1.0"
host: enterprise.influxdata.com
schemes:
    - http
basePath: /enterprise/v1
consumes:
    - application/json
produces:
    - application/json
paths:
    '/':
        get:
            summary: Lists all the endpoints
            description: List of the endpoints. 
            responses:
                200:
                    description: Returns the links to the top level endpoints.
                    schema:
                        $ref: '#/definitions/Links'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
    /sources:
        get:
            summary: Configured data sources
            description: These data sources store time series data.
            responses:
                200:
                    description: An array of data sources
                    schema:
                        $ref: '#/definitions/Sources'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
        post:
            summary: Create new data source
            parameters:
                - name: source
                  in: body
                  description: Configuration options for data source
                  schema:
                      $ref: '#/definitions/Source'
            responses:
                201:
                    description: Successfully create data source
                    headers:
                        Location:
                            type: string
                            format: url
                            description: Location of the newly created data source resource.
                    schema:
                        $ref: '#/definitions/Source'
                default:
                    description: A processing or an unexpected error.
                    schema:
                        $ref: '#/definitions/Error'
    /sources/{id}:
        get:
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
            summary: Configured data sources
            description: These data sources store time series data.
            responses:
                200:
                    description: Data source used to supply time series to dashboards.
                    schema:
                        $ref: '#/definitions/Source'
                404:
                    description: Unknown source id
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
        patch:
            summary: Update data source configuration
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of a data source
                  required: true
                - name: config
                  in: body
                  description: data source configuration
                  schema:
                      $ref: '#/definitions/Source'
                  required: true
            responses:
                204:
                    description: Data source's configuration was changed
                404:
                    description: Happens when trying to access a non-existent data source.
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: A processing or an unexpected error.
                    schema:
                        $ref: '#/definitions/Error'
        delete:
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the source
                  required: true
            summary: This specific data source will be removed from the data store
            responses:
                204:
                    description: data source has been removed
                404:
                    description: Unknown data source id
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
    /sources/{id}/proxy:
        post:
            description: Query the backend time series data source and return the response according to `format`
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
                - name: query
                  in: body
                  description: Query Parameters
                  schema:
                      $ref: '#/definitions/Proxy'
                  required: true
            responses:
                200:
                    description: Result of the query from the backend time series data source.
                    schema:
                        $ref: '#/definitions/ProxyResponse'
                400:
                    description: Any query that results in a data source error (syntax error, etc) will cause this response.  The error message will be passed back in the body
                    schema:
                        $ref: '#/definitions/Error'
                404:
                    description: Data source id does not exist.
                    schema:
                        $ref: '#/definitions/Error'
                408:
                    description: Timeout trying to query data source.
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
    /sources/{id}/queries:
        post:
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
                - name: query
                  in: body
                  description: Query Parameters
                  schema:
                      $ref: '#/definitions/Query'
                  required: true
            responses:
                201:
                    description: Responses from the data source backend in the query order from request.
                    headers:
                        Location:
                            type: string
                            format: url
                            description: Location of the newly created query resource.
                    schema:
                        $ref: '#/definitions/QueryResponse'
                400:
                    description: Any query that results in a data source error (syntax error, etc) will cause this response.  The error message will be passed back in the body
                    schema:
                        $ref: '#/definitions/Error'
                404:
                    description: Data source id does not exist.
                    schema:
                        $ref: '#/definitions/Error'
                408:
                    description: Timeout trying to query data source.
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
    /sources/{id}/queries/{qid}:
        get:
            summary: Return the configuration of the query including the resultsLink RPC endpoint.
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
                - name: qid
                  in: path
                  description: ID of stored query
                  required: true
                  type: string
            responses:
                200:
                    description: Query exists and the configuration is return
                    schema:
                        $ref: '#/definitions/QueryResponse'
                404:
                    description: source id or query id does not exist.
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
        patch:
            summary: Update specific query configuration parameters.
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
                - name: qid
                  in: path
                  description: ID of stored query
                  required: true
                  type: string
                - name: query
                  in: body
                  description: Query configuration parameters
                  schema:
                      $ref: '#/definitions/Query'
                  required: true
            responses:
                204:
                    description: Stored query has been updated
                404:
                    description: source id or query id does not exist.
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
        delete:
            summary: Destroy query resource
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
                - name: qid
                  in: path
                  description: ID of stored query
                  required: true
                  type: string
            responses:
                204:
                    description: Stored query has been destroyed.
                404:
                    description: source id or query id does not exist.
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
    /sources/{id}/queries/{qid}/results:
        get:
            summary: Return results from executing the query.
            description: |
                This endpoint acts as an RPC call to execute the query against the time series data source.
                The data source results are formatted before return according the the query's configuration.
                This endpoint also transforms the data source's error conditions into status codes 400 or 408.
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
                - name: qid
                  in: path
                  description: ID of stored query
                  required: true
                  type: string
                - name: lower
                  in: query
                  description: Optional lower-time bound override.  Will update the query configuration.
                  type: string
                - name: upper
                  in: query
                  description: Optional upper-time bound override.  Will update the query configuration.
                  type: string
            responses:
                200:
                    description: Query successfully executed and results have been transformed.
                    schema:
                        $ref: '#/definitions/QueryResults'
                400:
                    description: Any query that results in a data source error (syntax error, etc) will cause this response.  The error message will be passed back in the body
                    schema:
                        $ref: '#/definitions/Error'
                404:
                    description: source id or query id does not exist.
                    schema:
                        $ref: '#/definitions/Error'
                408:
                    description: Timeout trying to query data source.
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
    /sources/{id}/permissions:
        get:
            summary: Returns the list of possible permissions supported by the backend time series data source.
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
            responses:
                200:
                    description: An array of permissions
                    schema:
                        $ref: '#/definitions/ACL'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
    /sources/{id}/users:
        get:
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
            summary: List of all users on this data source
            responses:
                200:
                    description: An array of users
                    schema:
                        $ref: '#/definitions/Users'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
        post:
            summary: Create new user for this data source
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
                - name: user
                  in: body
                  description: Configuration options for new user
                  schema:
                      $ref: '#/definitions/User'
            responses:
                201:
                    description: Successfully created new user
                    headers:
                        Location:
                            type: string
                            format: url
                            description: Location of the newly created user resource.
                    schema:
                        $ref: '#/definitions/User'
                default:
                    description: A processing or an unexpected error.
                    schema:
                        $ref: '#/definitions/Error'
    /sources/{id}/users/{user_id}:
        get:
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
                - name: user_id
                  in: path
                  type: string
                  description: ID of the specific user
                  required: true
            summary: Returns information about a specific user
            description: |
                Specific User and their permissions.
            responses:
                200:
                    description: Information relating to the user
                    schema:
                        $ref: '#/definitions/User'
                404:
                    description: Unknown source id
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
        patch:
            summary: Update user configuration
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of a data source
                  required: true
                - name: user_id
                  in: path
                  type: string
                  description: ID of the specific user
                  required: true
                - name: config
                  in: body
                  description: user configuration
                  schema:
                      $ref: '#/definitions/User'
                  required: true
            responses:
                204:
                    description: Users's configuration was changed
                404:
                    description: Happens when trying to access a non-existent user.
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: A processing or an unexpected error.
                    schema:
                        $ref: '#/definitions/Error'
        delete:
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the source
                  required: true
                - name: user_id
                  in: path
                  type: string
                  description: ID of the specific user
                  required: true
            summary: This specific user will be removed from the data store
            responses:
                204:
                    description: User has been removed
                404:
                    description: Unknown user id
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
    /sources/{id}/roles:
        get:
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
            summary: List of all roles on this data source
            responses:
                200:
                    description: An array of roles
                    schema:
                        $ref: '#/definitions/Roles'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
        post:
            summary: Create new role for this data source
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
                - name: role
                  in: body
                  description: Configuration options for new role
                  schema:
                      $ref: '#/definitions/Role'
            responses:
                201:
                    description: Successfully created new role
                    headers:
                        Location:
                            type: string
                            format: url
                            description: Location of the newly created role resource.
                    schema:
                        $ref: '#/definitions/Role'
                default:
                    description: A processing or an unexpected error.
                    schema:
                        $ref: '#/definitions/Error'
    /sources/{id}/roles/{role_id}:
        get:
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the data source
                  required: true
                - name: role_id
                  in: path
                  type: string
                  description: ID of the specific role
                  required: true
            summary: Returns information about a specific role
            description: |
                Specific Role and its associated permissions.
            responses:
                200:
                    description: Information relating to the role
                    schema:
                        $ref: '#/definitions/Role'
                404:
                    description: Unknown source id
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
        patch:
            summary: Update role configuration
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of a data source
                  required: true
                - name: role_id
                  in: path
                  type: string
                  description: ID of the specific role
                  required: true
                - name: config
                  in: body
                  description: role configuration
                  schema:
                      $ref: '#/definitions/Role'
                  required: true
            responses:
                204:
                    description: Role's configuration was changed
                404:
                    description: Happens when trying to access a non-existent role.
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: A processing or an unexpected error.
                    schema:
                        $ref: '#/definitions/Error'
        delete:
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the source
                  required: true
                - name: role_id
                  in: path
                  type: string
                  description: ID of the specific role
                  required: true
            summary: This specific role will be removed from the data store
            responses:
                204:
                    description: Role has been removed
                404:
                    description: Unknown role id
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
    /dashboards:
        get:
            summary: Pre-configured dashboards
            description: |
                Dashboards are a collection of `Cells` that visualize time-series data.
            responses:
                200:
                    description: An array of dashboards 
                    schema:
                        $ref: '#/definitions/Dashboards'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
        post:
            summary: Create new Dashboard
            parameters:
                - name: dashboard
                  in: body
                  description: Defines the dashboard and queries of the cells within the dashboard.
                  schema:
                      $ref: '#/definitions/Dashboard'
            responses:
                201:
                    description: Successfully created new dashboard
                    headers:
                        Location:
                            type: string
                            format: url
                            description: Location of the newly created dashboard
                    schema:
                        $ref: '#/definitions/Dashboard'
                default:
                    description: A processing or an unexpected error.
                    schema:
                        $ref: '#/definitions/Error'
    /dashboards/{id}:
        get:
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the dashboard
                  required: true
            summary: Specific pre-configured dashboard containing cells and queries.
            description: |
                dashboards will hold information about how to layout the page of graphs.
            responses:
                200:
                    description: Returns the specified dashboard containing `cells`.
                    schema:
                        $ref: '#/definitions/Dashboard'
                404:
                    description: Unknown dashboard id
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
        delete:
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of the dashboard
                  required: true
            summary: This specific dashboard will be removed from the data store
            responses:
                204:
                    description: An array of dashboards
                404:
                    description: Unknown dashboard id
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: Unexpected internal service error
                    schema:
                        $ref: '#/definitions/Error'
        put:
            summary: Completely update dashboard configuration
            parameters:
                - name: id
                  in: path
                  type: string
                  description: ID of a dashboard
                  required: true
                - name: config
                  in: body
                  description: dashboard configuration update parameters
                  schema:
                      $ref: '#/definitions/Dashboard'
                  required: true
            responses:
                204:
                    description: Dashboard's configuration was changed
                404:
                    description: Happens when trying to access a non-existent dashboard.
                    schema:
                        $ref: '#/definitions/Error'
                default:
                    description: A processing or an unexpected error.
                    schema:
                        $ref: '#/definitions/Error'
definitions:
    Sources:
        type: object
        properties:
            sources:
                type: array
                items:
                    $ref: '#/definitions/Source'   
    Source:
        type: object
        required:
            - type
            - name
        properties:
            id:
                type: string
                description: Unique identifier representing a specific data source.
                readOnly: True
            name:
                type: string
                description: User facing name of data source
            type:
                type: string
                description: Format of the data source
                enum:
                    - influx
                    - influx-enterprise
            link:
                $ref: "#/definitions/Link"
    Roles:
        type: object
        properties:
            role:
                type: array
                items:
                    $ref: "#/definitions/Role"
    Role:
        type: object
        required:
            - id
            - permissions
            - name
        properties:
            id:
                type: string
            name:
                type: string
                maxLength: 64
            permissions:
                type: array
                items:
                    $ref: '#/definitions/Permission'
            link:
                $ref: "#/definitions/Link"
            users:
                $ref: "#/definitions/Links"
    Users:
        type: object
        properties:
            users:
                type: array
                items:
                    $ref: "#/definitions/User"
    User:
        type: object
        required:
            - id
            - permissions

        properties:
            id:
                type: string
            username:
                type: string
                maxLength: 64
            permissions:
                type: array
                items:
                    $ref: '#/definitions/Permission'
            link:
                $ref: "#/definitions/Link"
    Permission:
        type: object
        properties:
            database:
                type: string
            acls:
                $ref: "#/definitions/ACL"
    ACL:
        type: array
        items:
            $ref: "#/definitions/AC"
    AC:
        type: string
        description: Specific access 
        enum:
            - ViewAdmin
            - ViewChronograf
            - CreateDatabase
            - CreateUserAndRole
            - AddRemoveNode
            - DropDatabase
            - DropData
            - ReadData
            - WriteData
            - Rebalance
            - ManageShard
    Dashboards:
        type: object
        properties:
            dashboards:
                type: array
                items:
                    $ref: "#/definitions/Dashboard"
    Dashboard:
        type: object
        required:
            - cells
        properties:
            cells:
                type: array
                description: Cells are the individual visualization elements.
                items:
                    $ref: "#/definitions/Cell"
    Cell:
        type: object
        properties:
            x:
                description: X-coordinate of Cell in the Dashboard
                type: integer
                format: int32
            'y':
                description: Y-coordinate of Cell in the Dashboard
                type: integer
                format: int32
            w:
                description: Width of Cell in the Dashboard
                type: integer
                format: int32
            h:
                description: Height of Cell in the Dashboard
                type: integer
                format: int32
            queryLinks:
                description: Time-series data queries for Cell. GETs to these links produce `QueryResults.`
                type: array
                items:
                    type: string
                    format: url
    Error:
        type: object
        properties:
            code:
                type: integer
                format: int32
            message:
                type: string
    Links:
        type: object
        properties:
            links:
                type: array
                items:
                    $ref: "#/definitions/Link"
    Link:
        type: object
        required: [rel, href]
        readOnly: true
        description: URI of resource.
        properties:
            rel:
                type: string
            href:
                type: string
                format: url
    Proxy:
        type: object
        required:
            - query
        properties:
            query:
                type: string
            format:
                type: string
                enum:
                    - raw
                default: raw
    ProxyResponse:
        type: object
        properties:
            results:
                description: results from influx
                type: object
    Query:
        type: object
        properties:
            database:
                type: string
            measurement:
                type: string
            retentionPolicy:
                type: string
            fields:
                type: array
                items:
                    type: object
                    properties:
                        field:
                            type: string
                        funcs:
                            type: array
                            items:
                                type: string
            tags:
                type: object
            raw:
                type: string
            groupBy:
                type: object
                properties:
                    time: 
                        type: string
                        format: duration
                    tags:
                        type: array
                        items:
                            type: string
            format:
                type: string
                description: Query response format
                enum:
                    - raw
                default: raw
            protocol:
                type: string
                description: Protocol method to communicate results back (in the future this could include web sockets).
                enum:
                    - http
                default: http 
    QueryResponse:
        allOf: 
            - $ref: "#/definitions/Query"
            - type: object
              required:
                  - resultsLink
              properties:
                  resultsLink:
                      $ref: "#/definitions/Link"
    QueryResults:
        type: object
        required:
            - results
        properties:
            results:
                type: object