feat(API): add Linked Keys endpoints (#555)

* Add linked keys * Fix comments: Naming * Fix comments: Naming
phrase · Apr 2, 2024 · 4935dac · 4935dac
1 parent 0b36241
commit 4935dac
Show file tree

Hide file tree

Showing 9 changed files with 417 additions and 2 deletions.
diff --git a/clients/cli/go.sum b/clients/cli/go.sum
@@ -218,8 +218,8 @@ github.com/pascaldekloe/goe v0.0.0-20180627143212-57f6aae5913c/go.mod h1:lzWF7FI
 github.com/pelletier/go-toml v1.2.0/go.mod h1:5z9KED0ma1S8pY6P1sdut58dfprrGBbd/94hg7ilaic=
 github.com/pelletier/go-toml v1.8.1 h1:1Nf83orprkJyknT6h7zbuEGUEjcyVlCxSUGTENmNCRM=
 github.com/pelletier/go-toml v1.8.1/go.mod h1:T2/BmBdy8dvIRq1a/8aqjN41wvWlN4lrapLU/GW4pbc=
-github.com/phrase/phrase-go/v2 v2.23.0 h1:kNgS70kWdadLMttkgXj8I7Npw7xkRX7AWFkch/GBzqY=
-github.com/phrase/phrase-go/v2 v2.23.0/go.mod h1:ARQGM+rzC0tPf3Lf4pHoRKpGtmQnBa7V7LSVs3oJf0U=
+github.com/phrase/phrase-go/v2 v2.24.0 h1:3UAbj1SQne4j0X5Wp0O6tsgxp5hvcJuzdSE3x2E52Qo=
+github.com/phrase/phrase-go/v2 v2.24.0/go.mod h1:ARQGM+rzC0tPf3Lf4pHoRKpGtmQnBa7V7LSVs3oJf0U=
 github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/sftp v1.10.1/go.mod h1:lYOWFsE0bwd1+KfKJaKeuokY15vzFx25BLbzYYoAxZI=

diff --git a/doc/compiled.json b/doc/compiled.json
@@ -4240,6 +4240,53 @@
             }
           }
         ]
+      },
+      "key_link": {
+        "type": "object",
+        "properties": {
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The timestamp when the link was created."
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The timestamp when the link was last updated."
+          },
+          "created_by": {
+            "$ref": "#/components/schemas/user_preview",
+            "description": "The user who created the link."
+          },
+          "updated_by": {
+            "$ref": "#/components/schemas/user_preview",
+            "description": "The user who last updated the link."
+          },
+          "account": {
+            "$ref": "#/components/schemas/account",
+            "description": "The account associated with the link."
+          },
+          "parent": {
+            "$ref": "#/components/schemas/key_preview",
+            "description": "The parent translation key in the link."
+          },
+          "children": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/key_preview"
+            },
+            "description": "The child translation keys linked to the parent."
+          }
+        },
+        "required": [
+          "created_at",
+          "updated_at",
+          "created_by",
+          "updated_by",
+          "account",
+          "parent",
+          "children"
+        ]
       }
     },
     "parameters": {
@@ -26575,6 +26622,207 @@
         ],
         "x-cli-version": "2.7.0"
       }
+    },
+    "/projects/{project_id}/keys/{id}/key_links": {
+      "delete": {
+        "summary": "Batch unlink child keys from a parent key",
+        "description": "Unlinks multiple child keys from a given parent key in a single operation.",
+        "operationId": "key_links/batch_destroy",
+        "tags": [
+          "Linked Keys"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/X-PhraseApp-OTP"
+          },
+          {
+            "$ref": "#/components/parameters/account_id"
+          },
+          {
+            "in": "query",
+            "name": "unlink_parent",
+            "required": false,
+            "description": "Whether to unlink the parent key as well and unmark it as linked-key.",
+            "schema": {
+              "type": "boolean"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "required": [
+                  "child_key_ids"
+                ],
+                "type": "object",
+                "title": "key_links/batch_destroy/parameters",
+                "properties": {
+                  "child_key_ids": {
+                    "description": "The IDs of the child keys to unlink from the parent key.",
+                    "type": "array",
+                    "example": [
+                      "child_key_id1",
+                      "child_key_id2"
+                    ],
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "422": {
+            "$ref": "#/components/responses/422"
+          }
+        }
+      },
+      "get": {
+        "summary": "Retrieve all child keys linked to a specific parent key",
+        "description": "Returns detailed information about a parent key, including its linked child keys.",
+        "operationId": "key_links/index",
+        "tags": [
+          "Linked Keys"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/X-PhraseApp-OTP"
+          },
+          {
+            "$ref": "#/components/parameters/account_id"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/key_link"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "message": {
+                      "type": "string"
+                    }
+                  },
+                  "example": {
+                    "message": "Key <parent_key_code> is not a parent key"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "Link child keys to a parent key",
+        "description": "Creates links between a given parent key and one or more child keys.",
+        "operationId": "key_links/create",
+        "tags": [
+          "Linked Keys"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/X-PhraseApp-OTP"
+          },
+          {
+            "$ref": "#/components/parameters/account_id"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "required": [
+                  "child_key_ids"
+                ],
+                "type": "object",
+                "title": "key_links/create/parameters",
+                "properties": {
+                  "child_key_ids": {
+                    "description": "The IDs of the child keys to link to the parent key. Can be left empty, to only mark the given translation-key as parent",
+                    "type": "array",
+                    "example": [
+                      "child_key_id1",
+                      "child_key_id2"
+                    ],
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/key_link"
+                }
+              }
+            }
+          },
+          "422": {
+            "$ref": "#/components/responses/422"
+          }
+        }
+      }
+    },
+    "/projects/{project_id}/keys/{id}/key_links/{child_key_id}": {
+      "delete": {
+        "summary": "Unlink a child key from a parent key",
+        "description": "Unlinks a single child key from a given parent key.",
+        "operationId": "key_links/destroy",
+        "tags": [
+          "Linked Keys"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/X-PhraseApp-OTP"
+          },
+          {
+            "$ref": "#/components/parameters/account_id"
+          },
+          {
+            "in": "path",
+            "name": "child_key_id",
+            "required": true,
+            "description": "The ID of the child key to unlink.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "422": {
+            "$ref": "#/components/responses/422"
+          }
+        }
+      }
     }
   }
 }

diff --git a/paths.yaml b/paths.yaml
@@ -676,3 +676,13 @@
     "$ref": "./paths/organization_job_template_locales/update.yaml"
   delete:
     "$ref": "./paths/organization_job_template_locales/destroy.yaml"
+"/projects/{project_id}/keys/{id}/key_links":
+  delete:
+    "$ref": "./paths/key_links/batch_destroy.yaml"
+  get:
+    "$ref": "./paths/key_links/index.yaml"
+  post:
+    "$ref": "./paths/key_links/create.yaml"
+"/projects/{project_id}/keys/{id}/key_links/{child_key_id}":
+  delete:
+    "$ref": "./paths/key_links/destroy.yaml"
diff --git a/paths/key_links/batch_destroy.yaml b/paths/key_links/batch_destroy.yaml
@@ -0,0 +1,36 @@
+summary: Batch unlink child keys from a parent key
+description: Unlinks multiple child keys from a given parent key in a single operation.
+operationId: key_links/batch_destroy
+tags:
+- Linked Keys
+parameters:
+- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
+- "$ref": "../../parameters.yaml#/account_id"
+- in: query
+  name: unlink_parent
+  required: false
+  description: Whether to unlink the parent key as well and unmark it as linked-key.
+  schema:
+    type: boolean
+requestBody:
+  required: true
+  content:
+    application/json:
+      schema:
+        required:
+        - child_key_ids
+        type: object
+        title: key_links/batch_destroy/parameters
+        properties:
+          child_key_ids:
+            description: The IDs of the child keys to unlink from the parent key.
+            type: array
+            example: ["child_key_id1", "child_key_id2"]
+            items:
+              type: string
+
+responses:
+  '200':
+    description: OK
+  '422':
+    "$ref": "../../responses.yaml#/422"
diff --git a/paths/key_links/create.yaml b/paths/key_links/create.yaml
@@ -0,0 +1,35 @@
+---
+summary: Link child keys to a parent key
+description: Creates links between a given parent key and one or more child keys.
+operationId: key_links/create
+tags:
+- Linked Keys
+parameters:
+- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
+- "$ref": "../../parameters.yaml#/account_id"
+requestBody:
+  required: true
+  content:
+    application/json:
+      schema:
+        required:
+        - child_key_ids
+        type: object
+        title: key_links/create/parameters
+        properties:
+          child_key_ids:
+            description: The IDs of the child keys to link to the parent key. Can be left empty, to only mark the given translation-key as parent
+            type: array
+            example: ["child_key_id1", "child_key_id2"]
+            items:
+              type: string
+
+responses:
+  '201':
+    description: Created
+    content:
+      application/json:
+        schema:
+          "$ref": "../../schemas/key_link.yaml#/key_link"
+  '422':
+    "$ref": "../../responses.yaml#/422"
diff --git a/paths/key_links/destroy.yaml b/paths/key_links/destroy.yaml
@@ -0,0 +1,21 @@
+---
+summary: Unlink a child key from a parent key
+description: Unlinks a single child key from a given parent key.
+operationId: key_links/destroy
+tags:
+- Linked Keys
+parameters:
+- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
+- "$ref": "../../parameters.yaml#/account_id"
+- in: path
+  name: child_key_id
+  required: true
+  description: The ID of the child key to unlink.
+  schema:
+    type: string
+
+responses:
+  '200':
+    description: OK
+  '422':
+    "$ref": "../../responses.yaml#/422"