@shipeasy/openapi 1.5.0 → 2.1.0

package/spec/paths/metrics.yaml

@@ -0,0 +1,302 @@
+/api/admin/metrics:
+  get:
+    operationId: listMetrics
+    summary: List metrics
+    description: |-
+      Returns every metric in the project (not paginated) — name, folder, source event, the typed `queryIr`, and the rendered query.
+
+      **Use case:** Audit every metric defined in the project — for example to find the metric id to attach as an experiment's success metric.
+    tags:
+      - Metrics
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    responses:
+      "200":
+        description: List metrics
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/metrics.yaml#/ListMetricsResponse
+            example:
+              - id: met_01j7w8a1b2c3d4e5f6g7h8i9j0
+                name: checkouts
+                folder: null
+                eventName: checkout_completed
+                query: count_users(checkout_completed)
+                queryIr:
+                  agg: { kind: count_users }
+                  metric: checkout_completed
+                  filters: []
+                direction: higher_better
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+    x-cli:
+      name: list
+  post:
+    operationId: createMetric
+    summary: Create a metric
+    description: |-
+      Creates an event-backed metric. Pass the query as the DSL string (`query`) **or**
+      the typed IR (`query_ir`) — exactly one. `event_name` must equal the event the
+      query references.
+
+      Returns `409` if a metric with the same `name` already exists, and `422` if the
+      query is invalid or references an unregistered event / label.
+
+      **Use cases**
+
+      - **Track an event** — `count_users(<event>)` for unique-user counts.
+      - **Sum a value** — `sum(<event>, <label>)` for revenue / quantity metrics.
+      - **Experiment success metric** — create the metric, then attach its id to an experiment.
+    tags:
+      - Metrics
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/metrics.yaml#/CreateMetricRequest
+          examples:
+            countUsers:
+              summary: Count unique users (DSL)
+              description: Unique users who completed checkout, expressed with the query DSL.
+              value:
+                name: checkouts
+                event_name: checkout_completed
+                query: count_users(checkout_completed)
+            sumRevenue:
+              summary: Sum a value label (DSL)
+              description: Total revenue, summing the `amount` property of the `purchase` event.
+              value:
+                name: revenue
+                folder: checkout
+                event_name: purchase
+                query: sum(purchase, amount)
+                direction: higher_better
+            typedIr:
+              summary: Typed IR
+              description: Same metric supplied as the structured `query_ir` instead of the DSL.
+              value:
+                name: checkouts
+                event_name: checkout_completed
+                query_ir:
+                  agg:
+                    kind: count_users
+                  metric: checkout_completed
+                  filters: []
+    responses:
+      "201":
+        description: Create a metric
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/metrics.yaml#/CreateMetricResponse
+            example:
+              id: met_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: checkouts
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - ALREADY_EXISTS
+      - EVENT_PENDING
+      - REFERENCED_NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: create
+      positional:
+        - name
+/api/admin/metrics/{id}:
+  get:
+    operationId: getMetric
+    summary: Get a metric
+    description: |-
+      Fetch one metric by its id or name, including the rendered DSL query and the typed IR.
+
+      **Use case:** Inspect a single metric's full definition before reusing it in an experiment or alert rule.
+    tags:
+      - Metrics
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque metric id (`met_…`) or the metric's `name`.
+        schema:
+          type: string
+    responses:
+      "200":
+        description: Get a metric
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/metrics.yaml#/GetMetricResponse
+            example:
+              id: met_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: revenue
+              folder: checkout
+              eventName: purchase
+              query: sum(purchase, amount)
+              queryIr:
+                agg: { kind: sum }
+                metric: purchase
+                valueLabel: amount
+                filters: []
+              direction: higher_better
+              winsorizePct: 99
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: show
+      positional:
+        - id
+  patch:
+    operationId: updateMetric
+    summary: Update a metric
+    description: |-
+      Update a metric's definition — folder, source event, query (`query` DSL or typed `query_ir`), winsorisation, minimum detectable effect, or direction. `name` is immutable. Provide at most one of `query` / `query_ir`.
+
+      **Use case:** Refine a metric's query or guardrail direction without recreating it.
+    tags:
+      - Metrics
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque metric id (`met_…`) or the metric's `name`.
+        schema:
+          type: string
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/metrics.yaml#/UpdateMetricRequest
+          example:
+            direction: lower_better
+            winsorize_pct: 95
+    responses:
+      "200":
+        description: Update a metric
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/metrics.yaml#/GetMetricResponse
+            example:
+              id: met_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: revenue
+              direction: lower_better
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - id
+  delete:
+    operationId: deleteMetric
+    summary: Archive a metric
+    description: |-
+      Soft-deletes (archives) the metric. Returns `409` if it is attached to a running experiment — stop those experiments first.
+
+      **Use case:** Retire a metric once no running experiment depends on it (the user-facing verb is `archive`).
+    tags:
+      - Metrics
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque metric id (`met_…`) or the metric's `name`.
+        schema:
+          type: string
+    responses:
+      "200":
+        description: Archive a metric
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/metrics.yaml#/DeleteMetricResponse
+            example:
+              ok: true
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - REFERENCED_IN_USE
+    x-cli:
+      name: archive
+      positional:
+        - id