metrics-api-spec.yaml

swagger: "2.0"
info:
  title: Metrics API
  description: API reference for metrics. Root is https://some.server:{port}/v1/{tenant}/
  version: 1.0.0
host: some.server
schemes:
  - https
basePath: /v1/

paths:
  /{tenant}/metrics:
    get:
      summary: Returns a list of metrics.
      produces:
        - application/json
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/getMetricsResponse'
        400:
          description: Bad request.
        401:
          description: The request you have made requires authentication.
        403:
          description: Not authorized.
      parameters:
        - name: tenant
          in: path
          required: true
          type: string
        - name: namespace
          in: query
          type: string
        - name: query
          in: query
          type: string
          required: true
          description: |
            Query in MetricsQL eg cpu{host="server1", job="app1"}

  /{tenant}/labels:
    get:
      summary: Return a list of labels.
      responses:
        200:
          description: Ok
          schema:
            $ref: '#/definitions/getLabelsResponse'
        400:
          description: Bad request.
        401:
          description: The request you have made requires authentication.
        403:
          description: Not authorized.
      parameters:
        - name: tenant
          in: path
          required: true
          type: string

  /{tenant}/labels/{label}/values:
    get:
      summary: Return a list of values for label.
      responses:
        200:
          description: Ok
          schema:
            $ref: '#/definitions/getLabelValuesResponse'
        400:
          description: Bad request.
          schema:
            $ref: '#/definitions/errorBadRequest'
        401:
          description: The request you have made requires authentication.
        403:
          description: Not authorized.
      parameters:
        - name: tenant
          in: path
          required: true
          type: string
        - name: label
          in: path
          required: true
          type: string

  /{tenant}/query:
    get:
      summary: Return a query data.
      responses:
        200:
          description: Ok
          schema:
            $ref: '#/definitions/getQueryResponse'
        400:
          description: Bad request.
          schema:
            $ref: '#/definitions/errorBadRequest'
        401:
          description: The request you have made requires authentication.
        403:
          description: Not authorized.
        500:
          description: Internal error
      parameters:
        - name: tenant
          in: path
          required: true
          type: string
        - name: query
          in: query
          type: string
          description: |
            Query in MetricsQL eg `SUM BY(job) (cpu:Average{host="server1", job!="system"}[12h] offset 24h)`
        - name: namespace
          in: query
          type: string
          default: default


definitions:
  errorBadRequest:
    type: object
    properties:
      message:
        type: string
  user:
    type: object
    properties:
      project_id:
        type: string
      token:
        type: string

  metric:
    type: object
    properties:
      name:
        type: string
      path:
        type: string
      labels:
        type: object
    example: {"name": "cpu", "path": "cpu;host=server1", labels: {"host": "server1"}}

  getMetricsResponse:
    type: object
    properties:
      metrics:
        type: array
        items:
          $ref: '#/definitions/metric'

  getLabelsResponse:
    type: object
    properties:
      labels:
        type: array
        items:
          type: string
    example:
      simple:
        labels:
          - host
          - application
          - job
          - http_code

  getLabelValuesResponse:
    type: object
    properties:
      values:
        type: array
        items:
          type: string
    example:
      simple:
        values:
          - postgresql
          - nginx
          - node

  getQueryResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          result_type:
            type: string
          result:
            type: array
            items:
              type: object
              properties:
                metric:
                  $ref: '#/definitions/metric'
                values:
                  type: array
                  items:
                    type: array
                    items:
                      type: string
    example:
      one_metric:
        data:
          resut_type: vector
          result:
          - metric:
              name: cpu
              path: cpu;app=postgresql,host=server1
              labels:
                host: server1
                app: postgresql
            values:
              - - "2002-10-02T15:13:00"
                - "1.1"
              - - "2002-10-02T15:14:00"
                - "1.2"
      many_metrics:
        data:
          resut_type: vector
          result:
            - metric:
                name: cpu
                path: cpu;app=postgresql,host=server1
                labels:
                  host: server1
                  app: postgresql
              values:
                - - "2002-10-02T15:13:00"
                  - "1.1"
                - - "2002-10-02T15:14:00"
                  - "1.2"
            - metric:
                name: cpu
                path: cpu;app=postgresql,host=server2
                labels:
                  host: server2
                  app: postgresql
              values:
                - - "2002-10-02T15:13:00"
                  - "1.1"
                - - "2002-10-02T15:14:00"
                  - "1.2"