[APIM][GraphQL GA] How-to updates

Author: dlepow

articles/api-management/graphql-api.md

@@ -1,5 +1,5 @@
 ---
-title: Import a GraphQL API to Azure API Management | Microsoft Docs
+title: Add a GraphQL API to Azure API Management | Microsoft Docs
 titleSuffix: 
 description: Learn how to add an existing GraphQL service as an API in Azure API Management using the Azure portal, Azure CLI, or Azure PowerShell. Manage the API and enable queries to pass through to the GraphQL endpoint.
 ms.service: api-management
@@ -16,9 +16,8 @@ ms.custom: event-tier1-build-2022
 
 In this article, you'll:
 > [!div class="checklist"]
-> * Add a GraphQL API to your API Management instance.
+> * Add a pass-through GraphQL API to your API Management instance.
 > * Test your GraphQL API.
-> * Learn the limitations of your GraphQL API in API Management.
 
 If you want to import a GraphQL schema and set up field resolvers using REST or SOAP API endpoints, see [Import a GraphQL schema and set up field resolvers](graphql-schema-resolve-api.md).
 
@@ -55,16 +54,15 @@ If you want to import a GraphQL schema and set up field resolvers using REST or
     | **GraphQL API endpoint** | The base URL with your GraphQL API endpoint name. <br /> For example: *`https://example.com/your-GraphQL-name`*. You can also use a common "swapi" GraphQL endpoint such as `https://swapi-graphql.azure-api.net/graphql` as a demo. |
     | **Upload schema** | Optionally select to browse and upload your schema file to replace the schema retrieved from the GraphQL endpoint (if available).  |
     | **Description** | Add a description of your API. |
-    | **URL scheme** | Select **HTTP**, **HTTPS**, or **HTTP(S)**. Default selection: *HTTP(S)*. |
+    | **URL scheme** |  Make a selection based on your GraphQL endpoint. Select one of the options that includes a WebSocket scheme (**WS** or **WSS**) if your GraphQL API includes the subscription type. Default selection: *HTTP(S)*. |
     | **API URL suffix**| Add a URL suffix to identify this specific API in this API Management instance. It has to be unique in this API Management instance. |
     | **Base URL** | Uneditable field displaying your API base URL |
     | **Tags** | Associate your GraphQL API with new or existing tags. |
     | **Products** | Associate your GraphQL API with a product to publish it. |
-    | **Gateways** | Associate your GraphQL API with existing gateways. Default gateway selection: *Managed*. |
     | **Version this API?** | Select to apply a versioning scheme to your GraphQL API. |
 
 1. Select **Create**.
-1. After the API is created, browse the schema on the **Design** tab, in the **Frontend** section.
+1. After the API is created, browse or modify the schema on the **Design** tab.
        :::image type="content" source="media/graphql-api/explore-schema.png" alt-text="Screenshot of exploring the GraphQL schema in the portal.":::
 
 #### [Azure CLI](#tab/cli)

articles/api-management/graphql-schema-resolve-api.md

@@ -1,16 +1,16 @@
 ---
-title: Import GraphQL schema and set up field resolvers | Microsoft Docs
+title: Add a synthetic GraphQL API to Azure API Management | Microsoft Docs
 titleSuffix: 
-description: Import a GraphQL schema to API Management and configure a policy to resolve a GraphQL query using an HTTP-based data source.
+description: Add a synthetic GraphQL API by importing a GraphQL schema to API Management and configuring field resolvers that use HTTP-based data sources.
 ms.service: api-management
 author: dlepow
 ms.author: danlep
 ms.topic: how-to
-ms.date: 05/17/2022
+ms.date: 02/21/2023
 ms.custom: event-tier1-build-2022
 ---
 
-# Import a GraphQL schema and set up field resolvers
+# Add a synthetic GraphQL API and set up field resolvers
 
 
 [!INCLUDE [api-management-graphql-intro.md](../../includes/api-management-graphql-intro.md)]
@@ -20,7 +20,7 @@ ms.custom: event-tier1-build-2022
 In this article, you'll:
 > [!div class="checklist"]
 > * Import a GraphQL schema to your API Management instance
-> * Set up a resolver for a GraphQL query using an existing HTTP endpoints
+> * Set up a resolver for a GraphQL query using an existing HTTP endpoint
 > * Test your GraphQL API
 
 If you want to expose an existing GraphQL endpoint as an API, see [Import a GraphQL API](graphql-api.md).
@@ -45,28 +45,30 @@ If you want to expose an existing GraphQL endpoint as an API, see [Import a Grap
 
     :::image type="content" source="media/graphql-schema-resolve-api/create-from-graphql-schema.png" alt-text="Screenshot of fields for creating a GraphQL API.":::
 
-    | Field | Description |
+     | Field | Description |
     |----------------|-------|
     | **Display name** | The name by which your GraphQL API will be displayed. |
     | **Name** | Raw name of the GraphQL API. Automatically populates as you type the display name. |
-    | **Fallback GraphQL endpoint** | For this scenario, optionally enter a URL with a GraphQL API endpoint name. API Management passes GraphQL queries to this endpoint when a custom resolver isn't set for a field.    |
-    | **Upload schema file** | Select to browse and upload a valid GraphQL schema file with the `.graphql` extension. |
-    | Description | Add a description of your API. |
-    | URL scheme | Select **HTTP**, **HTTPS**, or **Both**. Default selection: *Both*. |
+    | **GraphQL type** | Select **Synthetic GraphQL** to import from a GraphQL schema file.  |
+    | **Fallback GraphQL endpoint** | Optionally enter a URL with a GraphQL API endpoint name. API Management passes GraphQL queries to this endpoint when a custom resolver isn't set for a field.  |
+    | **Description** | Add a description of your API. |
+    | **URL scheme** |  Make a selection based on your GraphQL endpoint. Select one of the options that includes a WebSocket scheme (**WS** or **WSS**) if your GraphQL API includes the subscription type. Default selection: *HTTP(S)*. |
     | **API URL suffix**| Add a URL suffix to identify this specific API in this API Management instance. It has to be unique in this API Management instance. |
     | **Base URL** | Uneditable field displaying your API base URL |
     | **Tags** | Associate your GraphQL API with new or existing tags. |
     | **Products** | Associate your GraphQL API with a product to publish it. |
-    | **Gateways** | Associate your GraphQL API with existing gateways. Default gateway selection: *Managed*. |
     | **Version this API?** | Select to apply a versioning scheme to your GraphQL API. |
+
 
 1. Select **Create**.
 
-1. After the API is created, browse the schema on the **Design** tab, in the **Frontend** section.
+1. After the API is created, browse or modify the schema on the **Design** tab.
 
 ## Configure resolver
 
-Configure the [set-graphql-resolver](set-graphql-resolver-policy.md) policy to map a field in the schema to an existing HTTP endpoint. 
+Configure a resolver to map a field in the schema to an existing HTTP endpoint. 
+
+<!-- Add link to resolver how-to article for details -->
 
 Suppose you imported the following basic GraphQL schema and wanted to set up a resolver for the *users* query.
 
@@ -82,24 +84,30 @@ type User {
 ```
 
 1. From the side navigation menu, under the **APIs** section, select **APIs** > your GraphQL API.
-1. On the **Design** tab of your GraphQL API, select **All operations**.
-1. In the **Backend** processing section, select **+ Add policy**.
-1. Configure the `set-graphql-resolver` policy to resolve the *users* query using an HTTP data source.
+1. On the **Design** tab, review the schema for a field in an object type where you want to configure a resolver. 
+    1. Select a field, and then in th
+    1. left margin, hover the pointer. 
+    1. Select **+ Add Resolver**
+
+        :::image type="content" source="media/graphql-schema-resolve-api/add-resolver.png" alt-text="Screenshot of adding a GraphQL resolver in the portal.":::
 
-    For example, the following `set-graphql-resolver` policy retrieves the *users* field by using a `GET` call on an existing HTTP data source.
+1. On the **Create Resolver** page, update the **Name** property if you want to, optionally enter a **Description**, and confirm or update the **Type** and **Field** selections.
 
+1. In the **Resolver policy** editor, update the `<http-data-source>` element with child elements for your scenario. For example, the following resolver retrieves the *users* field by using a `GET` call on an existing HTTP data source.
+
+    
     ```xml
-    <set-graphql-resolver parent-type="Query" field="users">
         <http-data-source>
             <http-request>
                 <set-method>GET</set-method>
                 <set-url>https://myapi.contoso.com/users</set-url>
             </http-request>
-        </http-data-source>
-    </set-graphql-resolver>
+        </http-data-source>\
     ```
-1. To resolve data for other fields in the schema, repeat the preceding step. 
-1. Select **Save**.
+
+    :::image type="content" source="media/graphql-schema-resolve-api/configure-resolver-policy.png" alt-text="Screenshot of configuring resolver policy in the portal.":::
+1. Select **Create**. 
+1. To resolve data for other fields in the schema, repeat the preceding steps to create a resolver. 
 
 [!INCLUDE [api-management-graphql-test.md](../../includes/api-management-graphql-test.md)]
 

articles/api-management/media/graphql-api/explore-schema.png

@@ -3,21 +3,9 @@ ms.service: api-management
 ms.topic: include
 author: dlepow
 ms.author: danlep
-ms.date: 05/17/2022
+ms.date: 02/21/2023
 ms.custom: 
 ---
 
-GraphQL is an open-source, industry-standard query language for APIs. Unlike endpoint-based (or REST-style) APIs designed around actions over resources, GraphQL APIs support a broader set of use cases and focus on data types, schemas, and queries.
-
-Using API Management to expose your GraphQL APIs, you can:
-* Add a GraphQL endpoint or GraphQL schema as an API via the Azure portal, the Azure CLI, or other Azure tools.
-* (Preview) Augment or design a GraphQL API using information from REST or SOAP APIs, using [HTTP resolvers](../articles/api-management/set-graphql-resolver-policy.md) for fields defined in a GraphQL schema. 
-* Secure GraphQL APIs by applying both existing access control policies and a [GraphQL validation policy](../articles/api-management/validate-graphql-request-policy.md) to secure and protect against GraphQL-specific attacks. 
-* Explore the schema and run test queries against the GraphQL APIs in the Azure and developer portals.
-
-> [!NOTE]
-> * A single GraphQL API in API Management can map to a single GraphQL backend endpoint.
-> * A GraphQL API requires a GraphQL schema, either from an existing GraphQL endpoint or uploaded by you.
-> * API Management supports query, mutation, and subscription operation types in GraphQL schemas. 
-> * Subscriptions are not supported in the **Consumption** service tier.
-> * A subscription must be implemented using the [graphql-ws](https://github.com/enisdenjo/graphql-ws) WebSocket protocol. Queries and mutations are not supported over WebSocket.
+In API Management, you can add a GraphQL API in one of two models: pass-through to an existing GraphQL endpoint, or import a GraphQL schema and create a synthetic GraphQL API with custom field resolvers. For more information, see the GraphQL overview.
+<!-- Add link to GraphQL overview when merged -->

articles/api-management/media/graphql-schema-resolve-api/add-resolver.png

@@ -34,8 +34,17 @@ ms.custom:
 1. Repeat preceding steps to test different payloads.
 1. When testing is complete, exit test console.
 
-> [!NOTE]
-> You can test a subscription in the test console:
-> * Set up a subscription query in the query editor, and then select **Connect** to establish a WebSocket connection to the backend service. 
-> * Review connection details in the **Subscription** pane. 
-> * The WebSocket connection is maintained until you disconnect it or you connect to a new WebSocket subscription.  
+## Test a subscription
+If your GraphQL schema includes a subscription, you can test it in the test console
+
+1. Ensure that your API allows a WebSocket URL scheme (**WS** or **WSS**) that's appropriate for your API. You can enable this setting on the **Settings** tab.
+1. Set up a subscription query in the query editor, and then select **Connect** to establish a WebSocket connection to the backend service. 
+
+    :::image type="content" source="media/api-management-graphql-test/test-graphql-subscription.png" alt-text="Screenshot of a subscription query in the query editor.":::
+1. Review connection details in the **Subscription** pane. 
+
+    :::image type="content" source="media/api-management-graphql-test/graphql-websocket-connection.png" alt-text="Screenshot of Websocket connection in the portal.":::
+    
+1. Subscribed events appear in the **Subscription** pane. The WebSocket connection is maintained until you disconnect it or you connect to a new WebSocket subscription.  
+
+    :::image type="content" source="media/api-management-graphql-test/graphql-subscription-event.png" alt-text="Screenshot of GraphQL subscription events in the portal.":::