Import a GraphQL API

APPLIES TO: All API Management tiers

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.

In this article, you'll:

• Add a pass-through GraphQL API to your API Management instance.
• Test your GraphQL API.

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.

Prerequisites

• An existing API Management instance. Create one if you haven't already.

• A GraphQL API.

• Azure CLI

  • Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.

    

  • If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

    • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

    • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

    • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

• Azure PowerShell

  • If you choose to use Azure PowerShell locally:
    • Install the latest version of the Az PowerShell module.
    • Connect to your Azure account using the Connect-AzAccount cmdlet.
  • If you choose to use Azure Cloud Shell:
    • See Overview of Azure Cloud Shell for more information.

Add a GraphQL API

Portal

1. In the Azure portal, navigate to your API Management instance.

2. In the left menu, select APIs > + Add API.

3. Under Define a new API, select the GraphQL icon.

   

4. In the dialog box, select Full and complete the required form fields.

   

   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.
   GraphQL type	Select Pass-through GraphQL to import from an existing GraphQL API endpoint.
   GraphQL API endpoint	The base URL with your GraphQL API endpoint name. 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	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.
   Version this API?	Select to apply a versioning scheme to your GraphQL API.

5. Select Create.

6. After the API is created, browse or modify the schema on the Design tab.

Azure CLI

The following example uses the az apim api import command to import a GraphQL passthrough API from the specified URL to an API Management instance named apim-hello-world.

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="my-graphql-api"
APIPath="myapi"
DisplayName="MyGraphQLAPI"
SpecificationFormat="GraphQL"
SpecificationURL="<GraphQL backend endpoint>"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --display-name $DisplayName --specification-format $SpecificationFormat --specification-url $SpecificationURL

After importing the API, if needed, you can update the settings by using the az apim api update command.

PowerShell

The following example uses the Import-AzApiManagementApi Azure PowerShell cmdlet to import a GraphQL passthrough API from the specified URL to an API Management instance named apim-hello-world.

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "my-graphql-api"
$apiPath = "myapi"
$specificationFormat = "GraphQL"
$specificationUrl = "<GraphQL backend endpoint>"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

After importing the API, if needed, you can update the settings by using the Set-AzApiManagementApi cmdlet.

Test your GraphQL API

1. Navigate to your API Management instance.

2. From the side navigation menu, under the APIs section, select APIs.

3. Under All APIs, select your GraphQL API.

4. Select the Test tab to access the test console.

5. Under Headers:

   1. Select the header from the Name drop-down menu.
   2. Enter the value to the Value field.
   3. Add more headers by selecting + Add header.
   4. Delete headers using the trashcan icon.

6. If you've added a product to your GraphQL API, apply product scope under Apply product scope.

7. Under Query editor, either:

   1. Select at least one field or subfield from the list in the side menu. The fields and subfields you select appear in the query editor.

   2. Start typing in the query editor to compose a query.

      

8. Under Query variables, add variables to reuse the same query or mutation and pass different values.

9. Select Send.

10. View the Response.

    

11. Repeat preceding steps to test different payloads.

12. When testing is complete, exit test console.

Test a subscription

If your GraphQL API supports 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.

2. Set up a subscription query in the query editor, and then select Connect to establish a WebSocket connection to the backend service.

   

3. Review connection details in the Subscription pane.

   

4. Subscribed events appear in the Subscription pane. The WebSocket connection is maintained until you disconnect it or you connect to a new WebSocket subscription.

   

Secure your GraphQL API

Secure your GraphQL API by applying both existing authentication and authorization policies and a GraphQL validation policy to protect against GraphQL-specific attacks.

Related topics

• API import limitations
• Import an OpenAPI specification
• Import a SOAP API
• Import a SOAP API and convert to REST
• Import an App Service API
• Import a Container App API
• Import a WebSocket API
• Import a GraphQL API
• Import a GraphQL schema and set up field resolvers
• Import an Azure Function App
• Import an Azure Logic App
• Import a Service Fabric service
• Import an OData API
• Import SAP OData metadata
• Import a gRPC API
• Edit an API

Next steps

Transform and protect a published API