openapi: 3.0.3
info:
  title: Devoteam DORA Metrics API
  description: ""
  contact:
    name: Devoteam DORA
    url: https://github.com/DevoteamNL/dora-backstage-plugin/issues
    email: dora@devoteam.com
  version: v1
  x-logo:
    altText: Devoteam Logo
    backgroundColor: "#FFFFFF"
    url: https://voortekst.nl/storage/clients/mqjWxe5KUrI1sytG3RPXtlKy9qgvLBuXgcqpwljm.png
    href: /
servers:
  - url: http://localhost:10666/dora/api
security:
  - BearerAuth: []
tags:
  - name: data-point
    description: <SchemaDefinition schemaRef="#/components/schemas/DataPoint" />
    x-displayName: DataPoint
  - name: response
    description: <SchemaDefinition schemaRef="#/components/schemas/MetricResponse" />
    x-displayName: MetricResponse
  - name: error-response
    description: <SchemaDefinition schemaRef="#/components/schemas/ErrorResponse" />
    x-displayName: ErrorResponse
paths:
  /metric:
    get:
      tags:
        - data-points
      summary: Query data points for a given DORA Metric
      description: |+
        Returns the data points for the requested metric according to the informed filters. The below are the metrics currently supported:

        | Metric Type     | Description                                                                         |
        | --------------- | ----------------------------------------------------------------------------------- |
        | `df_average`    | Deployment frequency (average), aggregated according to the `aggregation` parameter |
        | `df_count`      | Amount of Deployments, aggregated according to the `aggregation` parameter          |
        | `mltc`          | Median Lead Time for Changes, aggregated according to the `aggregation` parameter   |
        | `cfr`           | Change Failure Rate, aggregated according to the `aggregation` parameter            | 
        | `mttr`          | Mean Time to Recovery, aggregated according to the `aggregation` parameter          |

      operationId: dataPointsByMetrics
      parameters:
        - name: type
          in: query
          description: >-
            `required`. Specify the type of metric the data points should be retrieved to
          required: true
          schema:
            type: string
            enum:
              - df_average
              - df_count
              - mltc
              - cfr
              - mttr
        - name: aggregation
          in: query
          description: >-
            `optional`. Specify how the data points should be aggregated. If not informed, it will default to `weekly`
          schema:
            type: string
            enum:
              - weekly
              - monthly
              - quarterly
            default: weekly
        - name: project
          in: query
          description: >-
            `optional`. Specify the project/repo/component to which the data points should be retrieved
          schema:
            type: string
        - name: team
          in: query
          description: >-
            `optional`. Specify the team to which the data points should be retrieved
          schema:
            type: string
        - name: from
          in: query
          description: >-
            `optional`. Date/time from when the results should be filtered. If not informed, it will assume 6 months from the current date/time
            Should be before the 'to' param, and should always be paired with the 'to' param.
          schema:
            type: string
            format: date-time
            example: "2020-01-01T00:00:00Z"
        - name: to
          in: query
          description: >-
            `optional`. Date/time to when the results should be filtered. If not informed, it will assume the current date/time
            Should be before the current date/time and after the 'from' param, and should always be paired with the 'from' param.
          schema:
            type: string
            format: date-time
            example: "2020-01-31T23:59:59Z"
        - name: x-correlation-id
          in: header
          description: Unique identifer associated with the request
          schema:
            type: string
            format: uuid
          example: c0c62604-e3ab-4008-b882-4effcb4963ae
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetricResponse"
          headers:
            x-correlation-id:
              description: Unique identifer associated with the request
              schema:
                type: string
                format: uuid
              example: c0c62604-e3ab-4008-b882-4effcb4963ae
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            x-correlation-id:
              description: Unique identifer associated with the request
              schema:
                type: string
                format: uuid
              example: c0c62604-e3ab-4008-b882-4effcb4963ae
        "403":
          description: Forbidden! Access denied. Do not have authority to call this API
          content: {}
          headers:
            x-correlation-id:
              description: Unique identifer associated with the request
              schema:
                type: string
                format: uuid
              example: c0c62604-e3ab-4008-b882-4effcb4963ae
        "401":
          description: Unauthorized! Should Provide a valid JWT token
          content: {}
          headers:
            x-correlation-id:
              description: Unique identifer associated with the request
              schema:
                type: string
                format: uuid
              example: c0c62604-e3ab-4008-b882-4effcb4963ae
        "500":
          description: Internal error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Failed to connect to DevLake's DB
                reference: c0c62604-e3ab-4008-b882-4effcb4963ae
          headers:
            x-correlation-id:
              description: Unique identifer associated with the request
              schema:
                type: string
                format: uuid
              example: c0c62604-e3ab-4008-b882-4effcb4963ae
      security:
        - BearerAuth: []
  /benchmark:
    get:
      tags:
        - summary
      summary: Query the benchmark key for a given DORA Metric
      description: |+
        Returns a key corresponding to the benchmark calculated from the data points that match the filters. 
        The metrics currently supported are below:

        | Metric Type | Description                   | Benchmark keys                                 |
        | ----------- | ------------------------------| ---------------------------------------------- |
        | `df`        | Deployment frequency.         | on-demand, week-month, month-6month, lt-6month |
        | `mltc`      | Median lead time for changes. | lt-1hour, lt-1week, week-6month, mt-6month     |
        | `cfr`       | Change Failure Rate.          | lt-15p, 15-25p, 25-30p, mt-30p                 |       
        | `mttr`      | Mean Time to Recovery         | lt-1hour, lt-1day, day-week, mt-6month         |

      operationId: benchmarkByMetric
      parameters:
        - name: type
          in: query
          description: >-
            `required`. Specify the type of metric the benchmark should be calculated for
          required: true
          schema:
            type: string
            enum:
              - df
              - mltc
              - cfr
              - mttr
        - name: project
          in: query
          description: >-
            `optional`. Specify the project/repo/component to which the metric benchmark should be retrieved
          schema:
            type: string
        - name: team
          in: query
          description: >-
            `optional`. Specify the team to which the metric benchmark should be retrieved
          schema:
            type: string
        - name: from
          in: query
          description: >-
            `optional`. Date/time from when the results should be filtered. If not informed, it will assume 6 months from the current date/time
            Should be before the 'to' param, and should always be paired with the 'to' param.
            Time-span should be at least 6 months to get an accurate benchmark.
          schema:
            type: string
            format: date-time
            example: "2020-01-01T00:00:00Z"
        - name: to
          in: query
          description: >-
            `optional`. Date/time to when the results should be filtered. If not informed, it will assume the current date/time
            Should be before the current date/time and after the 'from' param, and should always be paired with the 'from' param.
          schema:
            type: string
            format: date-time
            example: "2020-01-31T23:59:59Z"
        - name: x-correlation-id
          in: header
          description: Unique identifer associated with the request
          schema:
            type: string
            format: uuid
          example: c0c62604-e3ab-4008-b882-4effcb4963ae
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BenchmarkResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Failed to connect to DevLake's DB
                reference: c0c62604-e3ab-4008-b882-4effcb4963ae
components:
  schemas:
    DataPoint:
      type: object
      required:
        - key
        - value
      properties:
        key:
          title: The key/label for the datapoint
          type: string
        value:
          title: "The numeric value of the metric, can be a Long or Double"
          type: number
          example: 103.5
    MetricResponse:
      type: object
      required:
        - aggregation
        - dataPoints
      properties:
        aggregation:
          title: Unit of aggregation used
          type: string
          example: weekly
        dataPoints:
          type: array
          items:
            $ref: "#/components/schemas/DataPoint"
    BenchmarkResponse:
      type: object
      required:
        - key
      properties:
        key:
          title: The key to identify the benchmark text
          description: month-6month would correspond to the text "Between once per month and once every 6 months" for example.
          type: string
          example: month-6month

    ErrorResponse:
      required:
        - message
        - reference
      type: object
      properties:
        message:
          title: Generic information about the failure
          type: string
          example: "You have requested an unsupported metric name, please check the metric parameter"
        reference:
          title: Generated ID to be able to trace more information about the error in the logs
          type: string
          example: c0c62604-e3ab-4008-b882-4effcb4963ae
  securitySchemes:
    BearerAuth:
      type: http
      description: A JWT Token provided by your OIDC Server
      scheme: bearer
      bearerFormat: JWT
x-tagGroups:
  - name: DORA
    tags:
      - data-points
      - summary
  - name: Models
    tags:
      - data-point
      - response
      - error-response