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"