swagger: "2.0"
info:
  description: "oMLet Metrics Service Definition"
  version: "1.0.0"
  title: "omlet_metrics_api"
  contact:
    name: "Infra"
    email: "infrateam@zoox.com"
    url: "https://git.zooxlabs.com/zooxco/driving"

basePath: "/v0"

tags:
  - name: "metrics"
    description: "Metrics Creation and Query Interfaces"

paths:
  "/metrics/{metricTypeId}":
    get:
      tags:
        - "metrics"
      summary: "List metrics by query"
      operationId: "getMetrics"
      produces:
        - "application/json"
      parameters:
        - name: "experimentId"
          in: "query"
          description: "Experiment ID."
          type: "string"
          required: True
        - name: "metricTypeId"
          in: "path"
          description: "Name of metric to return."
          type: "string"
          required: True
        - name: "order_by"
          in: "query"
          description: "The property to use for ordering the results."
          type: "string"
          required: False
          enum:
            - "timestamp"
            - "value"
        - name: "order_direction"
          in: "query"
          description: "The direction in which to order the results"
          type: "string"
          required: False
          enum:
            - "ascending"
            - "descending"
        - name: "offset"
          in: "query"
          description: "The offset at which to return the results"
          required: False
          type: "integer"
        - name: "limit"
          in: "query"
          description: "The max number of results to return"
          required: False
          type: "integer"
      responses:
        "200":
          description: "Successfully retrieved metrics."
          schema:
            $ref: "#/definitions/PaginatedMetricCollection"
          examples:
            application/json:
              data:
                - metricType:
                    id: "float_metric_id"
                    name: "Float Metric"
                    type: "float"
                  valFloat: 2.0
                  iteration: 1
                  timestamp: 1507074462000
                  experimentId: "abcd-efgh-ijkl"
                - metricType:
                    id: "float_metric_id"
                    name: "Float Metric"
                    type: "float"
                  valFloat: 6.0
                  iteration: 2
                  timestamp: 1507074466000
                  experimentId: "abcd-efgh-ijkl"
                - metricType:
                    id: "float_metric_id"
                    name: "Float Metric"
                    type: "float"
                  valFloat: 5.0
                  iteration: 10
                  timestamp: 1507074465000
                  experimentId: "abcd-efgh-ijkl"
              totalResults: 3
        "500":
          description: "Internal server error. Retry."
          schema:
            $ref: "#/definitions/ErrorResponse"

  "/metrics":
    post:
      tags:
      - "metrics"
      summary: "Report metrics."
      operationId: "createMetrics"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
        - name: "metrics"
          in: "body"
          description: "Metrics to create."
          required: True
          schema:
            $ref: "#/definitions/MetricCollection"
      responses:
        "201":
          description: "Successfuly created metrics."
          schema:
            $ref: "#/definitions/MetricCollection"
        "400":
          description: "Invalid Metric specification."
          schema:
            $ref: "#/definitions/ErrorResponse"
        "500":
          description: "Internal server error."
          schema:
            $ref: "#/definitions/ErrorResponse"

  "/metrics/latest":
    post:
      tags:
        - "metrics"
      summary: "List latest metrics"
      operationId: "getLatestMetrics"
      produces:
        - "application/json"
      parameters:
        - name: "experimentIds"
          in: "body"
          description: "An list of experiment IDs to filter by."
          required: True
          schema:
            type: "object"
            properties:
              experimentIds:
                type: "array"
                items:
                  type: "string"
      responses:
        "200":
          description: "Successfully retrieved metrics."
          schema:
            $ref: "#/definitions/PaginatedMetricCollection"
          examples:
            application/json:
              data:
                - metricType:
                    id: "float_metric_id"
                    name: "Float Metric"
                    type: "float"
                  valFloat: 6.0
                  iteration: 4
                  timestamp: 1507074465000
                  experimentId: "abcd-efgh-ijkl"
                - metricType:
                    id: "float_metric_id"
                    name: "Float Metric"
                    type: "float"
                  valFloat: 10.0
                  iteration: 3
                  timestamp: 1507074465000
                  experimentId: "an-id-for-u"
                - metricType:
                    id: "int_metric_id"
                    name: "Int Metric"
                    type: "integer"
                  valInt: 4
                  iteration: 11
                  timestamp: 1507074466000
                  experimentId: "abcd-efgh-ijkl"
              totalResults: 3

  "/metrics/types":
    get:
      tags:
        - "metrics"
      summary: "List metric types"
      operationId: "getMetricTypes"
      produces:
        - "application/json"
      parameters:
        - name: "experimentId"
          in: "query"
          description: "An experiment ID to filter by."
          type: "string"
          required: True
        - name: "offset"
          in: "query"
          description: "The offset at which to return the results"
          required: False
          type: "integer"
        - name: "limit"
          in: "query"
          description: "The max number of results to return"
          required: False
          type: "integer"
      responses:
        "200":
          description: "Successfully retrieved metric types."
          schema:
            $ref: "#/definitions/PaginatedMetricTypeCollection"
          examples:
            application/json:
              data:
                - id: "float_metric_id"
                  name: "Float Metric"
                  type: "float"
                - id: "int_metric_id"
                  name: "Int Metric"
                  type: "integer"
                - id: "bool_metric_id"
                  name: "Boolean Metric"
                  type: "bool"
              totalResults: 3

        "500":
          description: "Internal server error. Retry."
          schema:
            $ref: "#/definitions/ErrorResponse"

definitions:

  MetricType:
    type: "object"
    properties:
      id:
        type: "string"
        description: "The ID of this metric type."
      name:
        type: "string"
        description: "The metric's name."
      type:
        type: "string"
        enum:
          - "integer"
          - "bool"
          - "float"

  Metric:
    type: "object"
    properties:
      metricType:
        $ref: "#/definitions/MetricType"
      valFloat:
        description: "The metric's float value."
        type: "number"
        format: "float"
      valBool:
        description: "The metric's boolean value."
        type: "boolean"
      valInt:
        description: "The metric's boolean value."
        type: "integer"
        format: "int64"
      iteration:
        description: "The iteration after which this metric was reported. Set client side."
        type: "integer"
        format: "int64"
      timestamp:
        description: "Epoch metric timestamp in milliseconds. Set server side."
        type: "integer"
        format: "int64"
        readOnly: True
      experimentId:
        description: "The experiment to which this metric belongs."
        type: "string"
    required:
      - "metricType"
      - "experimentId"

  MetricCollection:
    type: "object"
    description: "A collection of a single metric"
    properties:
      data:
        type: "array"
        items:
          $ref: "#/definitions/Metric"

  PaginatedMetricCollection:
    type: "object"
    description: "A paginated collection of a single metric"
    properties:
      data:
        type: "array"
        items:
          $ref: "#/definitions/Metric"
      totalResults:
        description: "The total number of results this query will return"
        type: "integer"

  PaginatedMetricTypeCollection:
    type: "object"
    description: "A paginated collection of metric types"
    properties:
      data:
        type: "array"
        items:
          $ref: "#/definitions/MetricType"
      totalResults:
        description: "The total number of results this query will return"
        type: "integer"

  ErrorResponse:
    type: "object"
    properties:
      message:
        description: "A message describing the error"
        type: "string"
