@shipeasy/openapi 3.1.0 → 3.3.0

package/spec/paths/tags.yaml

@@ -0,0 +1,270 @@
+/api/admin/tags:
+  get:
+    operationId: listTags
+    summary: List the project's tags
+    description: |-
+      Returns every tag in the project — the shared roster any item (queue items, flags, configs, kill switches, metrics, tracked errors, alert rules, experiments) can carry. Sorted by name.
+
+      **Use case:** See which tags already exist before tagging an item, so you reuse `ios` instead of minting `iOS-app`.
+    tags:
+      - Tags
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: q
+        in: query
+        required: false
+        description: Case-insensitive substring filter on the tag name. Omit to return every tag.
+        schema:
+          type: string
+          maxLength: 64
+    responses:
+      "200":
+        description: List the project's tags
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/tags.yaml#/ListTagsResponse
+            example:
+              - id: tag_01j7w8a1b2c3d4e5f6g7h8i9j0
+                name: checkout
+              - id: tag_01j7w8a1b2c3d4e5f6g7h8i9j1
+                name: ios
+      "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
+/api/admin/tags/{entityType}/{entityId}:
+  get:
+    operationId: getEntityTags
+    summary: Read an item's tags
+    description: |-
+      Returns the tags attached to one item. The item is addressed by kind (`entityType`) plus its handle, so the same call reads tags off a queue item, a flag, a config, a kill switch, a metric, a tracked error, an alert rule, or an experiment.
+
+      **Use case:** Check an item's current tags before editing them.
+    tags:
+      - Tags
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: entityType
+        in: path
+        required: true
+        description: The kind of item — `ops`, `flag`, `config`, `killswitch`, `metric`, `error`, `alert_rule`, or `experiment`.
+        schema:
+          $ref: ../components/schemas/tags.yaml#/TaggableEntityType
+      - name: entityId
+        in: path
+        required: true
+        description: The item's handle — an ops item's number (e.g. `7`) or id; a flag/config/killswitch/metric/alert rule/experiment's name or id; a tracked error's id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Read an item's tags
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/tags.yaml#/EntityTagsResponse
+            example:
+              entityType: ops
+              entityId: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+              tags:
+                - checkout
+                - ios
+      "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: get
+      positional:
+        - entityType
+        - entityId
+  put:
+    operationId: setEntityTags
+    summary: Replace an item's tags
+    description: |-
+      Replaces the item's whole tag set with `tags`: names not yet in the project are created, attached names not in the list are detached, and `[]` clears every tag. Names are deduped case-insensitively, reusing an existing tag's casing (sending `iOS` when `ios` exists attaches `ios`).
+
+      **Use cases**
+
+      - **Tag an item** — `{ "tags": ["checkout", "ios"] }`.
+      - **Clear tags** — `{ "tags": [] }`.
+
+      To add or remove a few tags without restating the rest, use the incremental `PATCH` instead.
+    tags:
+      - Tags
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: entityType
+        in: path
+        required: true
+        description: The kind of item — `ops`, `flag`, `config`, `killswitch`, `metric`, `error`, `alert_rule`, or `experiment`.
+        schema:
+          $ref: ../components/schemas/tags.yaml#/TaggableEntityType
+      - name: entityId
+        in: path
+        required: true
+        description: The item's handle — an ops item's number (e.g. `7`) or id; a flag/config/killswitch/metric/alert rule/experiment's name or id; a tracked error's id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/tags.yaml#/SetEntityTagsRequest
+          examples:
+            tag:
+              summary: Set the item's tags
+              value:
+                tags:
+                  - checkout
+                  - ios
+            clear:
+              summary: Remove every tag
+              value:
+                tags: []
+    responses:
+      "200":
+        description: Replace an item's tags
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/tags.yaml#/EntityTagsResponse
+            example:
+              entityType: ops
+              entityId: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+              tags:
+                - checkout
+                - ios
+      "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: set
+      positional:
+        - entityType
+        - entityId
+  patch:
+    operationId: updateEntityTags
+    summary: Add or remove tags on an item
+    description: |-
+      Edits an item's tags incrementally: attaches every name in `add` (creating project tags as needed) and detaches every name in `remove`, leaving the item's other tags untouched. Matching is case-insensitive; a name in both lists ends up removed.
+
+      **Use cases**
+
+      - **Add a tag** — `{ "add": ["regression"] }`.
+      - **Swap a tag** — `{ "add": ["p1"], "remove": ["p2"] }`.
+    tags:
+      - Tags
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: entityType
+        in: path
+        required: true
+        description: The kind of item — `ops`, `flag`, `config`, `killswitch`, `metric`, `error`, `alert_rule`, or `experiment`.
+        schema:
+          $ref: ../components/schemas/tags.yaml#/TaggableEntityType
+      - name: entityId
+        in: path
+        required: true
+        description: The item's handle — an ops item's number (e.g. `7`) or id; a flag/config/killswitch/metric/alert rule/experiment's name or id; a tracked error's id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/tags.yaml#/UpdateEntityTagsRequest
+          examples:
+            add:
+              summary: Attach one tag
+              value:
+                add:
+                  - regression
+            swap:
+              summary: Replace one tag with another
+              value:
+                add:
+                  - p1
+                remove:
+                  - p2
+    responses:
+      "200":
+        description: Add or remove tags on an item
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/tags.yaml#/EntityTagsResponse
+            example:
+              entityType: ops
+              entityId: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+              tags:
+                - checkout
+                - ios
+      "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:
+        - entityType
+        - entityId