From f254d17f05343dcc4299fc53ff9b335b5ef63d69 Mon Sep 17 00:00:00 2001
From: "ct-sdks[bot]" <153784748+ct-sdks[bot]@users.noreply.github.com>
Date: Thu, 14 Nov 2024 15:15:30 +0000
Subject: [PATCH] Updated API from documentation release

---
 .../api/examples/GraphQL/GraphQLError.json    | 10 ++++----
 .../examples/GraphQL/GraphQLVariablesMap.json |  1 +
 .../api/examples/graphql-query.example.json   |  6 ++---
 api-specs/api/examples/graphql.example.json   | 23 +++----------------
 api-specs/api/resources/graphql.raml          |  4 ++--
 .../error/graphql/GraphQLErrorObject.raml     |  2 +-
 api-specs/api/types/graphql/GraphQLError.raml |  5 ++++
 .../types/graphql/GraphQLErrorLocation.raml   |  9 ++++++--
 .../api/types/graphql/GraphQLRequest.raml     |  6 ++++-
 .../api/types/graphql/GraphQLResponse.raml    |  6 ++++-
 .../types/graphql/GraphQLVariablesMap.raml    |  3 +++
 11 files changed, 41 insertions(+), 34 deletions(-)
 create mode 100644 api-specs/api/examples/GraphQL/GraphQLVariablesMap.json

diff --git a/api-specs/api/examples/GraphQL/GraphQLError.json b/api-specs/api/examples/GraphQL/GraphQLError.json
index 20ba971b3..b307d0699 100644
--- a/api-specs/api/examples/GraphQL/GraphQLError.json
+++ b/api-specs/api/examples/GraphQL/GraphQLError.json
@@ -1,12 +1,14 @@
 {
-  "message": "Cannot query field 'aaa' on type 'PaymentQueryResult'",
+  "message": "Object 35d33405-2d39-4528-b195-fa3ab6beb927 has a different version than expected. Expected: 1 - Actual: 2.",
+  "path": ["deleteProduct"],
   "locations": [
     {
-      "line": 3,
-      "column": 16
+      "line": 2,
+      "column": 3
     }
   ],
   "extensions": {
-    "code": "InvalidInput"
+    "code": "ConcurrentModification",
+    "currentVersion": 2
   }
 }
diff --git a/api-specs/api/examples/GraphQL/GraphQLVariablesMap.json b/api-specs/api/examples/GraphQL/GraphQLVariablesMap.json
new file mode 100644
index 000000000..9e8ea56fa
--- /dev/null
+++ b/api-specs/api/examples/GraphQL/GraphQLVariablesMap.json
@@ -0,0 +1 @@
+{ "productKey": "a-product-key" }
diff --git a/api-specs/api/examples/graphql-query.example.json b/api-specs/api/examples/graphql-query.example.json
index ffacb0298..cbbff2145 100644
--- a/api-specs/api/examples/graphql-query.example.json
+++ b/api-specs/api/examples/graphql-query.example.json
@@ -1,5 +1,5 @@
 {
-  "query": "\n      query query_1($productId: String){\n        product(key:$productId){\n          key\n        }\n      }\n    ",
-  "operationName": "query_1",
-  "variables": { "productId": "f8ded810-a1" }
+  "query": "query getProductByKey($productKey: String!) {  product(key: $productKey) { id version }}",
+  "operationName": "getProductByKey",
+  "variables": { "productKey": "a-product-key" }
 }
diff --git a/api-specs/api/examples/graphql.example.json b/api-specs/api/examples/graphql.example.json
index 2175623d6..d34345b5a 100644
--- a/api-specs/api/examples/graphql.example.json
+++ b/api-specs/api/examples/graphql.example.json
@@ -1,25 +1,8 @@
 {
   "data": {
-    "products": {
-      "results": [
-        {
-          "id": "00f230ac-da51-4a18-99eb-83368f1435b1",
-          "masterData": {
-            "staged": {
-              "skus": [
-                "test"
-              ],
-              "name": "Test"
-            },
-            "current": {
-              "skus": [
-                "test"
-              ],
-              "name": "Test"
-            }
-          }
-        }
-      ]
+    "product": {
+      "id": "35d33405-2d39-4528-b195-fa3ab6beb927",
+      "version": 2
     }
   }
 }
diff --git a/api-specs/api/resources/graphql.raml b/api-specs/api/resources/graphql.raml
index af6df4bcf..c3b1ab9ce 100644
--- a/api-specs/api/resources/graphql.raml
+++ b/api-specs/api/resources/graphql.raml
@@ -3,10 +3,10 @@ displayName: graphql
 description: commercetools Composable Commerce provides a GraphQL API
 post:
   displayName: GraphQL
-  description: Execute a GraphQL query
+  description: Execute a GraphQL request.
   securedBy: [oauth_2_0: { scopes: ['view_products:{projectKey}'] }]
   body:
-    application/graphql:
+    application/json:
       example: !include ../examples/graphql-query.example.json
       type: GraphQLRequest
   responses:
diff --git a/api-specs/api/types/error/graphql/GraphQLErrorObject.raml b/api-specs/api/types/error/graphql/GraphQLErrorObject.raml
index 739f09973..5845d92c0 100644
--- a/api-specs/api/types/error/graphql/GraphQLErrorObject.raml
+++ b/api-specs/api/types/error/graphql/GraphQLErrorObject.raml
@@ -8,7 +8,7 @@ properties:
   code:
     type: string
     description: |
-      Error identifier.
+      One of the error codes that is listed on the [Errors](/errors) page.
   //:
     type: any
     description: |
diff --git a/api-specs/api/types/graphql/GraphQLError.raml b/api-specs/api/types/graphql/GraphQLError.raml
index d9aa68030..b18cc1d40 100644
--- a/api-specs/api/types/graphql/GraphQLError.raml
+++ b/api-specs/api/types/graphql/GraphQLError.raml
@@ -2,15 +2,20 @@
 (package): GraphQL
 displayName: GraphQLError
 type: object
+description: Contains an error message, the location of the code that caused the error, and other information to help you correct the error.
 example: !include ../../examples/GraphQL/GraphQLError.json
 properties:
   message:
     type: string
+    description: Detailed description of the error explaining the root cause of the problem and suggesting how to correct the error.
   locations:
     type: array
     items: GraphQLErrorLocation
+    description: Location within your query where the error occurred.
   path?:
     type: array
     items: any
+    description: Query fields listed in order from the root of the query response up to the field in which the error occurred. `path` is displayed in the response only if an error is associated with a particular field in the query result.
   extensions:
     type: GraphQLErrorObject
+    description: Dictionary with additional information where applicable.
diff --git a/api-specs/api/types/graphql/GraphQLErrorLocation.raml b/api-specs/api/types/graphql/GraphQLErrorLocation.raml
index 393d11dbf..8b6cdc20a 100644
--- a/api-specs/api/types/graphql/GraphQLErrorLocation.raml
+++ b/api-specs/api/types/graphql/GraphQLErrorLocation.raml
@@ -2,8 +2,13 @@
 (package): GraphQL
 displayName: GraphQLErrorLocation
 type: object
+description: Represents the location within your query where the error occurred.
 properties:
   line:
-    type: integer
+    type: number
+    format: int64
+    description: Line number of the query where the error occurred.
   column:
-    type: integer
+    type: number
+    format: int64
+    description: Position in `line` where the error occurred.
diff --git a/api-specs/api/types/graphql/GraphQLRequest.raml b/api-specs/api/types/graphql/GraphQLRequest.raml
index 24eda544f..a10896419 100644
--- a/api-specs/api/types/graphql/GraphQLRequest.raml
+++ b/api-specs/api/types/graphql/GraphQLRequest.raml
@@ -1,12 +1,16 @@
 #%RAML 1.0 DataType
 (package): GraphQL
 displayName: GraphQLRequest
+example: !include ../../examples/graphql-query.example.json
+description: The query, operation name, and variables that are sent to the GraphQL API.
 type: object
 properties:
   query:
     type: string
+    description: String representation of the _Source Text_ of the _Document_ that is specified in the [Language section of the GraphQL specification](https://spec.graphql.org/draft/#sec-Language).
   operationName?:
     type: string
+    description: Name of the operation, if you defined several operations in `query`.
   variables?:
     type: GraphQLVariablesMap
-    description: ''
+    description: JSON object that contains key-value pairs in which the keys are variable names and the values are variable values.
diff --git a/api-specs/api/types/graphql/GraphQLResponse.raml b/api-specs/api/types/graphql/GraphQLResponse.raml
index 0349e9091..9a54e7f32 100644
--- a/api-specs/api/types/graphql/GraphQLResponse.raml
+++ b/api-specs/api/types/graphql/GraphQLResponse.raml
@@ -2,10 +2,14 @@
 (package): GraphQL
 displayName: GraphQLResponse
 type: object
+example: !include ../../examples/graphql.example.json
+description: |
+  `error` is present in the response only if the GraphQL query was unsuccessful.
 properties:
   data?:
     type: any
+    description: JSON object that contains the results of a GraphQL query.
   errors?:
     type: array
     items: GraphQLError
-    description: ''
+    description: Errors that the GraphQL query returns.
diff --git a/api-specs/api/types/graphql/GraphQLVariablesMap.raml b/api-specs/api/types/graphql/GraphQLVariablesMap.raml
index 302a4044e..3ff08f5fc 100644
--- a/api-specs/api/types/graphql/GraphQLVariablesMap.raml
+++ b/api-specs/api/types/graphql/GraphQLVariablesMap.raml
@@ -2,6 +2,9 @@
 (package): GraphQL
 displayName: GraphQLVariablesMap
 type: object
+description: The variables that the GraphQL query uses.
+example: !include ../../examples/GraphQL/GraphQLVariablesMap.json
 properties:
   //:
     type: any
+    description: JSON object that contains key-value pairs in which the keys are variable names and the values are variable values.