catalyst/definition/dashboards.yaml

swagger: "2.0"
info: { version: "", title: "" }

paths:
  /statistics:
    get:
      tags: [ "statistics" ]
      summary: "Get statistics"
      operationId: "getStatistics"
      responses:
        "200":
          description: "successful operation"
          schema: { $ref: '#/definitions/Statistics' }
          examples:
            test:
              unassigned: 0
              open_tickets_per_user: { }
              tickets_per_week: { "2021-39": 3 }
              tickets_per_type: { "alert": 2, "incident": 1 }
      security: [ { roles: [ "ticket:read" ] } ]

  /dashboards:
    get:
      tags: [ "dashboards" ]
      summary: "List dashboards"
      operationId: "listDashboards"
      responses:
        "200":
          description: "successful operation"
          schema: { type: array, items: { $ref: "#/definitions/DashboardResponse" } }
          examples:
            test:
              - id: simple
                name: Simple
                widgets:
                  - name: "open_tickets_per_user"
                    aggregation: "owner"
                    filter: 'status == "open"'
                    type: "bar"
                    width: 4
                  - name: "tickets_per_week"
                    aggregation: 'CONCAT(DATE_YEAR(created), "-", DATE_ISOWEEK(created) < 10 ? "0" : "", DATE_ISOWEEK(created))'
                    type: "line"
                    width: 8
      security: [ { roles: [ "dashboard:read" ] } ]
    post:
      tags: [ "dashboards" ]
      summary: "Create a new dashboard"
      operationId: "createDashboard"
      parameters:
        - { name: "template", in: "body", description: "New template", required: true, schema: { $ref: "#/definitions/Dashboard" }, x-example: { name: "My Dashboard", widgets: [ ] } }
      responses:
        "200":
          description: "successful operation"
          schema: { $ref: "#/definitions/DashboardResponse" }
          examples:
            test:
              id: "my-dashboard"
              name: "My Dashboard"
              widgets: []
      security: [ { roles: [ "dashboard:write" ] } ]

  /dashboards/{id}:
    get:
      tags: [ "dashboards" ]
      summary: "Get a single dashboard"
      operationId: "getDashboard"
      parameters:
        - { name: "id", in: "path", description: "Dashboard ID", required: true, type: string, x-example: "simple" }
      responses:
        "200":
          description: "successful operation"
          schema: { $ref: "#/definitions/DashboardResponse" }
          examples:
            test:
              id: simple
              name: Simple
              widgets:
                - name: "open_tickets_per_user"
                  aggregation: "owner"
                  filter: 'status == "open"'
                  type: "bar"
                  width: 4
                - name: "tickets_per_week"
                  aggregation: 'CONCAT(DATE_YEAR(created), "-", DATE_ISOWEEK(created) < 10 ? "0" : "", DATE_ISOWEEK(created))'
                  type: "line"
                  width: 8
      security: [ { roles: [ "dashboard:read" ] } ]
    put:
      tags: [ "dashboards" ]
      summary: "Update an existing dashboard"
      operationId: "updateDashboard"
      parameters:
        - { name: "id", in: "path", description: "Dashboard ID", required: true, type: string, x-example: "simple" }
        - { name: "dashboard", in: "body", description: "Dashboard object that needs to be added", required: true, schema: { $ref: "#/definitions/Dashboard" }, x-example: { name: "Simple", widgets: [] } }
      responses:
        "200":
          description: "successful operation"
          schema: { $ref: "#/definitions/DashboardResponse" }
          examples:
            test:
              id: simple
              name: Simple
              widgets: []
      security: [ { roles: [ "dashboard:write" ] } ]
    delete:
      tags: [ "dashboards" ]
      summary: "Delete a dashboard"
      operationId: "deleteDashboard"
      parameters:
        - { name: "id", in: "path", description: "Dashboard ID", required: true, type: string, x-example: "simple" }
      responses:
        "204": { description: "successful operation" }
      security: [ { roles: [ "dashboard:write" ] } ]

  /dashboard/data:
    get:
      tags: [ "dashboards" ]
      summary: "Get widget data"
      operationId: "dashboardData"
      parameters:
        - { name: "aggregation", in: "query", description: "Aggregation", required: true, type: string, x-example: "type" }
        - { name: "filter", in: "query", description: "Filter", type: string, x-example: 'status == "closed"' }
      responses:
        "200":
          description: "successful operation"
          schema: { type: object }
          examples:
            test:
              alert: 2
              incident: 1
      security: [ { roles: [ "dashboard:read" ] } ]

definitions:
  Statistics:
    type: object
    required: [ unassigned, open_tickets_per_user, tickets_per_week, tickets_per_type ]
    properties:
      unassigned: { type: integer }
      open_tickets_per_user: { type: object, additionalProperties: { type: integer } }
      tickets_per_week: { type: object, additionalProperties: { type: integer } }
      tickets_per_type: { type: object, additionalProperties: { type: integer } }

  Dashboard:
    type: object
    required: [ name, widgets ]
    properties:
      name: { type: string }
      widgets: { type: array, items: { $ref: "#/definitions/Widget" } }

  DashboardResponse:
    type: object
    required: [ id, name, widgets ]
    properties:
      id: { type: string }
      name: { type: string }
      widgets: { type: array, items: { $ref: "#/definitions/Widget" } }

  Widget:
    type: object
    required: [ name, type, aggregation, width ]
    properties:
      name: { type: string }
      type: { type: string, enum: [ "bar", "line", "pie" ] }
      filter: { type: string }
      aggregation: { type: string }
      width: { type: integer, minimum: 1, maximum: 12 }