# OpenAPI spec describing a subset of the HTTP REST API for the cc-metric-store.

openapi: 3.0.3
info:
  title: 'cc-metric-store REST API'
  description: 'In-memory time series database for hpc metrics to be used with the [ClusterCockpit](https://github.com/ClusterCockpit) toolsuite'
  version: 0.1.0
paths:
  '/api/write':
    post:
      operationId: 'writeMetrics'
      description: 'Recieves metrics in the influx line-protocol using [this format](https://github.com/ClusterCockpit/cc-specifications/blob/master/metrics/lineprotocol_alternative.md)'
      parameters:
        - name: cluster
          in: query
          schema: { type: string }
          description: "If the lines in the body do not have a cluster tag, use this value instead."
      requestBody:
        required: true
        content:
          'text/plain':
            example:
              'flops_any,cluster=emmy,hostname=e1001,type=cpu,type-id=0 value=42.0'
      responses:
        200:
          description: 'Everything went fine'
        400:
          description: 'Bad Request'
  '/api/query':
    post:
      operationId: 'queryMetrics'
      description: 'Query metrics'
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              type: object
              required: [cluster, from, to]
              properties:
                cluster:
                  type: string
                from:
                  type: integer
                to:
                  type: integer
                with-stats:
                  type: boolean
                  default: true
                with-data:
                  type: boolean
                  default: true
                queries:
                  type: array
                  items:
                    $ref: '#/components/schemas/ApiQuery'
                for-all-nodes:
                  description: 'If not null, add a new query for every known host on that cluster and every metric (at node-scope) specified in this array to the request. This can be used to get a metric for every host in a cluster without knowing the name of every host.'
                  type: array
                  items:
                    type: string
      responses:
        200:
          description: 'Requested data and stats as JSON'
          content:
            'application/json':
              schema:
                type: object
                properties:
                  queries:
                    description: 'Only if for-all-nodes was used, this property exists.'
                  results:
                    type: array
                    description: 'Array where each element is a response to the query at that same index in the request'
                    items:
                      description: 'If `aggreg` is true, only ever has one element.'
                      type: array
                      items:
                        type: object
                        properties:
                          error:
                            description: 'If not null or undefined, an error happend processing that query'
                            type: string
                            nullable: true
                          data:
                            type: array
                            items:
                              type: number
                              nullable: true
                          avg: { type: number }
                          min: { type: number }
                          max: { type: number }
        400:
          description: 'Bad Request'
  '/api/free':
    post:
      operationId: 'freeBuffers'
      description: 'Allow all buffers containing only data older than `to`'
      parameters:
        - name: to
          in: query
          description: 'Unix Timestamp'
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              type: array
              items:
                type: array
                items:
                  type: string
      responses:
        200:
          description: 'Everything went fine'
        400:
          description: 'Bad Request'
components:
  schemas:
    ApiQuery:
      description: 'A single query for a specific metric resulting in one series'
      type: object
      required: [metric, hostname, aggreg]
      properties:
        metirc:
          type: string
        hostname:
          type: string
        type:
          description: 'Not required for node-level requests. Usually something like socket, cpu or hwthread.'
          type: string
        type-ids:
          type: array
          items:
            type: integer
        aggreg:
          type: boolean
          description: 'If true, every query result will have exactly one element. Otherwise, the data for every requested type-id/sub-type-id is provided seperately'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: [] # Applies `bearerAuth` globally