GraphQL: backport restructuring changes from 2.3.4 and general cleanup

_data/toc/graphql.yml

@@ -13,12 +13,6 @@ pages:
         - label: Get customer authorization token
           url: /graphql/get-customer-authorization-token.html
 
-        - label: Queries
-          url: /graphql/queries.html
-
-        - label: Mutations
-          url: /graphql/mutations.html
-
         - label: GraphQL Caching
           url: /graphql/caching.html
 
@@ -47,6 +41,9 @@ pages:
 
     - label: Queries
       children:
+        - label: Using queries
+          url: /graphql/queries/index.html
+
         - label: cart query
           url: /graphql/queries/cart.html
 
@@ -112,6 +109,9 @@ pages:
 
     - label: Mutations
       children:
+        - label: Using mutations
+          url: /graphql/mutations/index.html
+
         - label: addConfigurableProductsToCart mutation
           url: /graphql/mutations/add-configurable-products.html
 
@@ -214,11 +214,14 @@ pages:
         - label: updateCustomerAddress mutation
           url: /graphql/mutations/update-customer-address.html
 
-    - label: Product data types and interfaces
+    - label: Catalog data types and interfaces
       children:
         - label: Product interface implementations
           url: /graphql/product/product-interface-implementations.html
 
+        - label: ProductInterface attributes
+          url: /graphql/product/product-interface.html
+
         - label: CustomizableOptionInterface
           url: /graphql/product/customizable-option-interface.html
 

_data/whats-new.yml

@@ -1150,7 +1150,7 @@ entries:
   date: March 26, 2019
   link: https://github.com/magento/devdocs/pull/3867
 - description: The "Searches and Pagination" topic  has been expanded to include more
-    information about queries and renamed to ["Queries"](https://devdocs.magento.com/guides/v2.3/graphql/queries.html).
+    information about queries and renamed to ["Using queries"](https://devdocs.magento.com/guides/v2.3/graphql/queries/index.html).
   versions: 2.3.1
   type: Major update
   date: March 26, 2019
@@ -1176,7 +1176,7 @@ entries:
   type: Major update
   date: March 26, 2019
   link: https://github.com/magento/devdocs/pull/3851
-- description: Added a topic on [GraphQL mutations](https://devdocs.magento.com/guides/v2.3/graphql/mutations.html)
+- description: Added a topic on [GraphQL mutations](https://devdocs.magento.com/guides/v2.3/graphql/mutations/index.html)
   versions: 2.3.1
   type: New topic
   date: March 26, 2019

_includes/graphql/cart-object.md

@@ -3,13 +3,13 @@ Attribute |  Data Type | Description
 `applied_coupon` | [`AppliedCoupon`][AppliedCoupon] | The `AppliedCoupon` object contains the `code` text attribute, which specifies the coupon code
 `applied_gift_cards` | [[`AppliedGiftCard`]][AppliedGiftCard] | An array of `AppliedGiftCard` objects. An `AppliedGiftCard` object contains the `code` text attribute, which specifies the gift card code. `applied_gift_cards` is a Commerce-only attribute, defined in the GiftCardAccountGraphQl module
 `applied_store_credit` | [`AppliedStoreCredit`][AppliedStoreCredit] | Contains store credit information applied to the cart. `applied_store_credit` is a Commerce-only attribute, defined in the CustomerBalanceGraphQl module
-`available_payment_methods` | [AvailablePaymentMethod][AvailablePaymentMethod] | Available payment methods
-`billing_address` | [BillingCartAddress][BillingCartAddress] | Contains the billing address specified in the customer's cart
+`available_payment_methods` | [[AvailablePaymentMethod]][AvailablePaymentMethod] | Available payment methods
+`billing_address` | [BillingCartAddress][BillingCartAddress]! | Contains the billing address specified in the customer's cart
 `email` | String | The customer's email address
-`items` | [CartItemInterface][CartItemInterface] | Contains the items in the customer's cart
+`items` | [[CartItemInterface]][CartItemInterface] | Contains the items in the customer's cart
 `prices` | [CartPrices][CartPrices] | Contains subtotals and totals
 `selected_payment_method` | [SelectedPaymentMethod][SelectedPaymentMethod] | Selected payment method
-`shipping_addresses` | [ShippingCartAddress][ShippingCartAddress] | Contains one or more shipping addresses
+`shipping_addresses` | [[ShippingCartAddress]][ShippingCartAddress]! | Contains one or more shipping addresses
 
 [AppliedCoupon]: {{page.baseurl}}/graphql/queries/cart.html#AppliedCoupon
 [AppliedGiftCard]: {{page.baseurl}}/graphql/queries/cart.html#AppliedGiftCard

guides/v2.3/graphql/develop/create-graphqls-file.md

@@ -22,7 +22,7 @@ The base `schema.graphqls` file, located in the `app/code/Magento/GraphQl/etc/`
 
 A query definition can be one line, or it can be complex. If your module's query implements `searchCriteria`, then you must define arguments that define filters and pagination information, all of which adds complexity. However, if you expect a single result from your query, then its definition can be simple.
 
-The following example shows the `products` query. The `type` is defined as a `Query`.  The `products` definitions define the keywords that are used to construct a query, as shown in [Queries]({{ page.baseurl }}/graphql/queries.html). The parameter definitions will be discussed in [Specify output attributes](#specify-output-attributes).
+The following example shows the `products` query. The `type` is defined as a `Query`.  The `products` definitions define the keywords that are used to construct a query, as shown in [Queries]({{ page.baseurl }}/graphql/queries/index.html). The parameter definitions will be discussed in [Specify output attributes](#specify-output-attributes).
 
 ```text
 type Query {

guides/v2.3/graphql/index.md

@@ -47,4 +47,4 @@ GraphiQL is an in-browser tool for writing, validating, and testing GraphQL quer
 
 ![GraphiQL browser]({{ page.baseurl }}/graphql/images/graphql-browser.png)
 
-To begin using GraphiQL, set the GraphQL endpoint by entering `http://<magento2-3-server>/graphql` in the URL bar, then click **Set endpoint**. You can use the browser in the right column to determine how to set up a query. Additional examples are also available in [Queries]({{ page.baseurl }}/graphql/queries.html).
+To begin using GraphiQL, set the GraphQL endpoint by entering `http://<magento2-3-server>/graphql` in the URL bar, then click **Set endpoint**. You can use the browser in the right column to determine how to set up a query. Additional examples are also available in [Queries]({{ page.baseurl }}/graphql/queries/index.html).

guides/v2.3/graphql/mutations/add-configurable-products.md

@@ -22,7 +22,7 @@ mutation {
       cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C"
       cart_items: [
         {
-          variant_sku: "MH02"
+          parent_sku: "MH02"
           data: {
             quantity: 2
             sku: "MH02-XS-Black"
@@ -59,12 +59,20 @@ mutation {
       "cart": {
         "items": [
           {
-            "id": "26",
+            "id": "5",
             "quantity": 2,
             "product": {
-              "name": "Teton Pullover Hoodie-XS-Black",
-              "sku": "MH02-XS-Black"
-            }
+              "name": "Teton Pullover Hoodie",
+              "sku": "MH02"
+            },
+            "configurable_options": [
+              {
+                "option_label": "Color"
+              },
+              {
+                "option_label": "Size"
+              }
+            ]
           }
         ]
       }
@@ -81,8 +89,8 @@ The `AddConfigurableProductsToCartInput` object contains the following attribute
 
 Attribute | Type | Description
 --- | --- | ---
-`cart_items` | [[ConfigurableProductCartItemInput]](#configProdCartItemInput) | An array of configurable items to add to the cart
 `cart_id` | String | The unique ID that identifies the customer's cart
+`cart_items` | [[ConfigurableProductCartItemInput]](#configProdCartItemInput) | An array of configurable items to add to the cart
 
 ### ConfigurableProductCartItemInput object {#configProdCartItemInput}
 
@@ -91,8 +99,9 @@ The `ConfigurableProductCartItemInput` object contains the following attributes:
 Attribute | Type | Description
 --- | --- | ---
 `customizable_options` | [CustomizableOptionInput](#customOptionInput) | An object that contains the ID and value of the product
-`data` | [CartItemInput](#cartItemInput) | An object that contains the quantity and SKU of the configurable product
-`variant_sku` | String | The SKU of the simple product
+`data` | [CartItemInput!](#cartItemInput) | An object that contains the quantity and SKU of the configurable product
+`parent_sku` | String | The SKU of the simple product's parent configurable product
+`variant_sku` | String | Deprecated. Use `CartItemInput.sku` instead. The SKU of the simple product
 
 ### CustomizableOptionInput object {#customOptionInput}
 
@@ -109,8 +118,8 @@ The `CartItemInput` object contains the following attributes:
 
 Attribute | Type | Description
 --- | --- | ---
-`quantity` | Float | The number of configurable items to add to the cart
-`sku` | String | The SKU of the configurable product
+`quantity` | Float! | The number of items to add to the cart
+`sku` | String! | The SKU of the simple product
 
 ## Output attributes
 

guides/v2.3/graphql/mutations/apply-giftcard.md

@@ -18,7 +18,7 @@ The following example adds a gift card with the code `0330CEIVTLB4` to the cart.
 
 **Request**
 
-``` text
+```graphql
 mutation {
   applyGiftCardToCart(
     input: {

guides/v2.3/graphql/mutations/apply-store-credit.md

@@ -23,7 +23,7 @@ In the following example, the customer starts with $10 of store credit. The subt
 
 **Request**
 
-```text
+```graphql
 mutation {
   applyStoreCreditToCart(
     input: {

guides/v2.3/graphql/mutations/change-customer-password.md

@@ -9,7 +9,7 @@ To return or modify information about a customer, Magento recommends you use cus
 
 ## Syntax
 
-`mutation: {changeCustomerPassword(currentPassword: String!newPassword: String!) {Customer}}`
+`mutation: {changeCustomerPassword(currentPassword: String! newPassword: String!) {Customer}}`
 
 ## Example usage
 
@@ -44,7 +44,7 @@ mutation {
 
 ## Input attributes
 
-The `changeCustomerPassword` object requires the following inputs:
+The `changeCustomerPassword` mutation requires the following inputs:
 
 Attribute |  Data Type | Description
 --- | --- | ---

guides/v2.3/graphql/mutations/create-empty-cart.md

@@ -19,7 +19,7 @@ If you are creating a cart for a logged in customer, you must include the custom
 
 **Request**
 
-```text
+```graphql
 mutation {
   createEmptyCart
 }

guides/v2.3/graphql/mutations/delete-customer-address.md

@@ -35,12 +35,16 @@ mutation {
 
 ## Input attributes
 
-The `deleteCustomerAddress` object requires the following input:
+The `deleteCustomerAddress` mutation requires the following input:
 
 Attribute |  Data Type | Description
 --- | --- | ---
 `id` | Int! | The ID assigned to the address object
 
+## Output attributes
+
+The `deleteCustomerAddress` mutation returns a Boolean value that indicates whether the operation was successful.
+
 ## Related topics
 
 * [customer query]({{page.baseurl}}/graphql/queries/customer.html)

guides/v2.3/graphql/mutations/generate-customer-token.md

@@ -42,13 +42,21 @@ mutation {
 
 ## Input attributes
 
-The `generateCustomerToken` object requires the following inputs:
+The `generateCustomerToken` mutation requires the following inputs:
 
 Attribute |  Data Type | Description
 --- | --- | ---
 `email` | String | The customer's email address
 `password` | String | The customer's password
 
+## Output attributes
+
+The `generateCustomerToken` mutation returns a valid token for the customer.
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`token` | String | The customer token
+
 ## Related topics
 
 * [customer query]({{page.baseurl}}/graphql/queries/customer.html)

guides/v2.3/graphql/mutations.md → guides/v2.3/graphql/mutations/index.md

@@ -1,6 +1,8 @@
 ---
 group: graphql
-title: Mutations
+title: Using mutations
+redirect_from:
+  - /guides/v2.3/graphql/mutations.html
 ---
 
 While GraphQL queries perform read operations, mutations change the data. A mutation can create, update, or delete objects and fields. In REST terminology, queries operate like `GET` requests, while mutations are similar to `POST`, `PUT`, and `DELETE`.

guides/v2.3/graphql/mutations/place-order.md

@@ -63,8 +63,14 @@ Attribute |  Data Type | Description
 
 ## Output attributes
 
-The `placeOrderOutput` object contains the `order` object, which contains the following attribute:
+The `placeOrderOutput` object returns an `order` object.
 
 Attribute |  Data Type | Description
 --- | --- | ---
-`order_id` | String! | The unique ID that identifies the order
+`order` | Order! | The unique ID that identifies the order
+
+### Order object
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`order_id` | String | The unique ID that identifies the order

guides/v2.3/graphql/mutations/redeem-giftcard-balance.md

@@ -19,7 +19,7 @@ The following example redeems the gift card with code `“056MHP57TJ5C”`.
 
 **Request**
 
-``` text
+```graphql
 mutation {
   redeemGiftCardBalanceAsStoreCredit(
     input : { gift_card_code: “056MHP57TJ5C”}

guides/v2.3/graphql/mutations/remove-coupon.md

@@ -80,19 +80,15 @@ mutation {
 
 ## Input attributes
 
-The `removeCouponFromCart` mutation requires the `cart_id` attribute.
-
-### removeCouponFromCart object {#removeCouponFromCart}
-
-The `removeCouponFromCart` object must contain the following attributes:
+The `removeCouponFromCart` mutation must contain the following attribute:
 
 Attribute |  Data Type | Description
 --- | --- | ---
 `cart_id` | String! | The unique ID that identifies the customer's cart
 
 ## Output attributes
 
-The `removeCouponFromCart` object contains the `Cart` object.
+The `removeCouponFromCart` mutation returns the `Cart` object.
 
 Attribute |  Data Type | Description
 --- | --- | ---

guides/v2.3/graphql/mutations/remove-giftcard.md

@@ -49,11 +49,7 @@ mutation {
 
 ## Input attributes
 
-The `removeGiftCardFromCart` mutation requires the `cart_id` attribute.
-
-### removeGiftCardFromCart object {#removeGiftCardFromCart}
-
-The `removeGiftCardFromCart` object must contain the following attributes:
+The `removeGiftCardFromCartInput` object must contain the following attributes:
 
 Attribute |  Data Type | Description
 --- | --- | ---
@@ -62,7 +58,7 @@ Attribute |  Data Type | Description
 
 ## Output attributes
 
-The `removeGiftCardFromCart` object contains the `Cart` object.
+The `removeGiftCardFromCartOutput` object contains the `Cart` object.
 
 Attribute |  Data Type | Description
 --- | --- | ---

guides/v2.3/graphql/mutations/remove-item.md

@@ -17,7 +17,7 @@ The following example removes cart item 14 from the cart.
 
 **Request**
 
-```text
+```graphql
 mutation {
   removeItemFromCart(
     input: {

guides/v2.3/graphql/mutations/remove-store-credit.md

@@ -16,7 +16,7 @@ Store credit must be enabled on the store to run this mutation.
 
 **Request**
 
-```text
+```graphql
 mutation {
   removeStoreCreditFromCart(
     input: {

guides/v2.3/graphql/mutations/set-billing-address.md

@@ -17,7 +17,7 @@ The following example creates a new billing address for a specific cart.
 
 **Request**
 
-``` text
+```graphql
 mutation {
   setBillingAddressOnCart(
     input: {

guides/v2.3/graphql/mutations/set-guest-email.md

@@ -17,7 +17,7 @@ A logged-in customer specifies an email address when they create an account. The
 
 **Request**
 
-``` text
+```graphql
 mutation {
   setGuestEmailOnCart(
     input: {