Updated API from documentation release

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
   }
 }

api-specs/api/examples/GraphQL/GraphQLVariablesMap.json

@@ -0,0 +1 @@
+{ "productKey": "a-product-key" }

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" }
 }

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
     }
   }
 }

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:

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: |

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.

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.

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.

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.

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.