Import a GraphQL API
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 for fields defined in a GraphQL schema.
- Secure GraphQL APIs by applying both existing access control policies and a GraphQL validation policy 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.
- 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 WebSocket protocol. Queries and mutations are not supported over WebSocket.
In this article, you'll:
- Learn more about the benefits of using GraphQL APIs.
- Add a 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.
An existing API Management instance. Create one if you haven't already.
A GraphQL API.
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.
Add a GraphQL API
In the Azure portal, navigate to your API Management instance.
In the left menu, select APIs > + Add API.
Under Define a new API, select the GraphQL icon.
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 API endpoint The base URL with your GraphQL API endpoint name.
https://example.com/your-GraphQL-name. You can also use a common "Star Wars" GraphQL endpoint such as
https://swapi-graphql.azure-api.net/graphqlas 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 Both. Default selection: Both. 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.
After the API is created, browse the schema on the Design tab, in the Frontend section.
Test your GraphQL API
Navigate to your API Management instance.
From the side navigation menu, under the APIs section, select APIs.
Under All APIs, select your GraphQL API.
Select the Test tab to access the test console.
- Select the header from the Name drop-down menu.
- Enter the value to the Value field.
- Add more headers by selecting + Add header.
- Delete headers using the trashcan icon.
If you've added a product to your GraphQL API, apply product scope under Apply product scope.
Under Query editor, either:
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.
Start typing in the query editor to compose a query.
Under Query variables, add variables to reuse the same query or mutation and pass different values.
View the Response.
Repeat preceding steps to test different payloads.
When testing is complete, exit test console.
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.
- 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 SAP OData metadata
- Edit an API