feat(API): add linked_key field to key list responses #STRINGS-4425

clients/java/src/test/java/com/phrase/client/api/KeysApiTest.java

@@ -240,7 +240,8 @@ public void keysListTest() throws ApiException {
         String order = null;
         String q = null;
         String localeId = null;
-        List<TranslationKey> response = api.keysList(projectId, xPhraseAppOTP, page, perPage, branch, sort, order, q, localeId);
+        Boolean includeLinkedKeys = null;
+        List<TranslationKey> response = api.keysList(projectId, xPhraseAppOTP, page, perPage, branch, sort, order, q, localeId, includeLinkedKeys);
 
         // TODO: test validations
     }
@@ -260,7 +261,8 @@ public void keysSearchTest() throws ApiException {
         String xPhraseAppOTP = null;
         Integer page = null;
         Integer perPage = null;
-        List<TranslationKey> response = api.keysSearch(projectId, keysSearchParameters, xPhraseAppOTP, page, perPage);
+        Boolean includeLinkedKeys = null;
+        List<TranslationKey> response = api.keysSearch(projectId, keysSearchParameters, xPhraseAppOTP, page, perPage, includeLinkedKeys);
 
         // TODO: test validations
     }

doc/compiled.json

@@ -2880,6 +2880,10 @@
           "updated_at": {
             "type": "string",
             "format": "date-time"
+          },
+          "linked_key": {
+            "description": "Only returned by the list and search endpoints when `include_linked_keys=true` is passed. `null` means the key is not linked.\n",
+            "$ref": "#/components/schemas/translation_key_linked_key"
           }
         },
         "example": {
@@ -2965,6 +2969,54 @@
           }
         ]
       },
+      "translation_key_linked_key": {
+        "type": "object",
+        "nullable": true,
+        "title": "translation_key_linked_key",
+        "description": "Describes a key's role in a parent–child link relationship.",
+        "properties": {
+          "role": {
+            "type": "string",
+            "description": "Whether this key is the parent or the child in the link relationship.",
+            "enum": [
+              "parent",
+              "child"
+            ]
+          },
+          "parent": {
+            "$ref": "#/components/schemas/translation_key_linked_key_parent"
+          },
+          "children_count": {
+            "type": "integer",
+            "nullable": true,
+            "description": "The number of linked child keys. Set for parent keys.",
+            "example": 3
+          }
+        },
+        "example": {
+          "role": "parent",
+          "parent": null,
+          "children_count": 3
+        }
+      },
+      "translation_key_linked_key_parent": {
+        "type": "object",
+        "nullable": true,
+        "description": "The parent key's public identifier and name. Set for child keys.",
+        "title": "translation_key_linked_key_parent",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The parent key's public identifier (code).",
+            "example": "abc12345def67890abc12345def67890"
+          },
+          "name": {
+            "type": "string",
+            "description": "The parent key's name.",
+            "example": "home.welcome.title"
+          }
+        }
+      },
       "affected_resources": {
         "type": "object",
         "title": "affected_resources",
@@ -24355,6 +24407,15 @@
             "schema": {
               "type": "string"
             }
+          },
+          {
+            "name": "include_linked_keys",
+            "in": "query",
+            "description": "When set to `true`, each key object in the response includes a `linked_key` field describing whether the key is a parent or child in a key-link relationship, and the number of children (for parent keys) or the parent's id and name (for child keys). Keys with no active link return `linked_key: null`. Omit this parameter or set it to `false` to leave the `linked_key` field out of the response entirely.\n",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            }
           }
         ],
         "responses": {
@@ -24727,6 +24788,15 @@
           },
           {
             "$ref": "#/components/parameters/per_page"
+          },
+          {
+            "name": "include_linked_keys",
+            "in": "query",
+            "description": "When set to `true`, each key object in the response includes a `linked_key` field describing whether the key is a parent or child in a key-link relationship, and the number of children (for parent keys) or the parent's id and name (for child keys). Keys with no active link return `linked_key: null`. Omit this parameter or set it to `false` to leave the `linked_key` field out of the response entirely.\n",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            }
           }
         ],
         "responses": {

openapi-generator/templates/go/model.mustache

@@ -34,7 +34,7 @@ type {{classname}} struct {
 {{#description}}
 	// {{{description}}}
 {{/description}}
-	{{name}} {{#isNullable}}*{{/isNullable}}{{^isNullable}}{{#isBoolean}}*{{/isBoolean}}{{/isNullable}}{{{dataType}}} `{{#vendorExtensions.x-json-tag}}{{{.}}}{{/vendorExtensions.x-json-tag}}{{^vendorExtensions.x-json-tag}}json:"{{baseName}}{{^required}},omitempty{{/required}}"{{/vendorExtensions.x-json-tag}}{{#withXml}} xml:"{{baseName}}{{#isXmlAttribute}},attr{{/isXmlAttribute}}"{{/withXml}}{{#vendorExtensions.x-go-custom-tag}} {{{.}}}{{/vendorExtensions.x-go-custom-tag}}`
+	{{name}} {{#isNullable}}*{{/isNullable}}{{^isNullable}}{{#isBoolean}}*{{/isBoolean}}{{/isNullable}}{{#isModel}}{{#isNullable}}{{{complexType}}}{{/isNullable}}{{^isNullable}}{{{dataType}}}{{/isNullable}}{{/isModel}}{{^isModel}}{{{dataType}}}{{/isModel}} `{{#vendorExtensions.x-json-tag}}{{{.}}}{{/vendorExtensions.x-json-tag}}{{^vendorExtensions.x-json-tag}}json:"{{baseName}}{{^required}},omitempty{{/required}}"{{/vendorExtensions.x-json-tag}}{{#withXml}} xml:"{{baseName}}{{#isXmlAttribute}},attr{{/isXmlAttribute}}"{{/withXml}}{{#vendorExtensions.x-go-custom-tag}} {{{.}}}{{/vendorExtensions.x-go-custom-tag}}`
 {{/allVars}}
 }
 {{/isEnum}}

paths/keys/index.yaml

@@ -34,6 +34,18 @@ parameters:
   in: query
   schema:
     type: string
+- name: include_linked_keys
+  in: query
+  description: >
+    When set to `true`, each key object in the response includes a
+    `linked_key` field describing whether the key is a parent or child in a
+    key-link relationship, and the number of children (for parent keys) or
+    the parent's id and name (for child keys). Keys with no active link
+    return `linked_key: null`. Omit this parameter or set it to `false` to
+    leave the `linked_key` field out of the response entirely.
+  required: false
+  schema:
+    type: boolean
 responses:
   '200':
     description: OK

paths/keys/search.yaml

@@ -9,6 +9,18 @@ parameters:
 - "$ref": "../../parameters.yaml#/project_id"
 - "$ref": "../../parameters.yaml#/page"
 - "$ref": "../../parameters.yaml#/per_page"
+- name: include_linked_keys
+  in: query
+  description: >
+    When set to `true`, each key object in the response includes a
+    `linked_key` field describing whether the key is a parent or child in a
+    key-link relationship, and the number of children (for parent keys) or
+    the parent's id and name (for child keys). Keys with no active link
+    return `linked_key: null`. Omit this parameter or set it to `false` to
+    leave the `linked_key` field out of the response entirely.
+  required: false
+  schema:
+    type: boolean
 responses:
   '200':
     description: OK

schemas.yaml

@@ -96,6 +96,10 @@ schemas:
     "$ref": schemas/translation_key.yaml#/translation_key
   translation_key_details:
     "$ref": schemas/translation_key_details.yaml#/translation_key_details
+  translation_key_linked_key:
+    "$ref": schemas/translation_key_linked_key.yaml#/translation_key_linked_key
+  translation_key_linked_key_parent:
+    "$ref": schemas/translation_key_linked_key_parent.yaml#/translation_key_linked_key_parent
   affected_resources:
     "$ref": schemas/affected_resources.yaml#/affected_resources
   translation_order:

schemas/translation_key.yaml

@@ -27,6 +27,11 @@ translation_key:
     updated_at:
       type: string
       format: date-time
+    linked_key:
+      description: >
+        Only returned by the list and search endpoints when
+        `include_linked_keys=true` is passed. `null` means the key is not linked.
+      "$ref": "./translation_key_linked_key.yaml#/translation_key_linked_key"
   example:
     id: abcd1234cdef1234abcd1234cdef1234
     name: home.index.headline

schemas/translation_key_linked_key.yaml

@@ -0,0 +1,24 @@
+---
+translation_key_linked_key:
+  type: object
+  nullable: true
+  title: translation_key_linked_key
+  description: Describes a key's role in a parent–child link relationship.
+  properties:
+    role:
+      type: string
+      description: Whether this key is the parent or the child in the link relationship.
+      enum:
+      - parent
+      - child
+    parent:
+      "$ref": "./translation_key_linked_key_parent.yaml#/translation_key_linked_key_parent"
+    children_count:
+      type: integer
+      nullable: true
+      description: The number of linked child keys. Set for parent keys.
+      example: 3
+  example:
+    role: parent
+    parent:
+    children_count: 3

schemas/translation_key_linked_key_parent.yaml

@@ -0,0 +1,15 @@
+---
+translation_key_linked_key_parent:
+  type: object
+  nullable: true
+  description: The parent key's public identifier and name. Set for child keys.
+  title: translation_key_linked_key_parent
+  properties:
+    id:
+      type: string
+      description: The parent key's public identifier (code).
+      example: abc12345def67890abc12345def67890
+    name:
+      type: string
+      description: The parent key's name.
+      example: home.welcome.title