|
| 1 | +--- |
| 2 | +title: Support for GraphQL APIs - Azure API Management |
| 3 | +description: Learn about GraphQL and how Azure API Management helps you manage GraphQL APIs. |
| 4 | +services: api-management |
| 5 | +author: dlepow |
| 6 | + |
| 7 | +ms.service: api-management |
| 8 | +ms.topic: conceptual |
| 9 | +ms.date: 02/14/2023 |
| 10 | +ms.author: danlep |
| 11 | +--- |
| 12 | + |
| 13 | +# Overview of GraphQL APIs in Azure API Management |
| 14 | + |
| 15 | +You can use API Management to manage GraphQL APIs - APIs based on the GraphQL query language. GraphQL provides a complete and understandable description of the data in an API, giving clients the power to efficiently retrieve exactly the data they need. [Learn more about GraphQL]( https://graphql.org/learn/) |
| 16 | + |
| 17 | +API Management helps you import, manage, protect, test, publish, and monitor GraphQL APIs. You can choose one of two API models: |
| 18 | + |
| 19 | + |
| 20 | +|Pass-through GraphQL |Synthetic GraphQL | |
| 21 | +|---------|---------| |
| 22 | +| ▪️ Pass-through API to existing GraphQL service endpoint<br><br/>▪️ Support for GraphQL queries, mutations, and subscriptions | ▪️ API based on a custom GraphQL schema<br></br>▪️ Support for GraphQL queries, mutations, and subscriptions<br/><br/>▪️ Configure custom resolvers, for example, to HTTP data sources<br/><br/>▪️ Develop GraphQL schemas and GraphQL-based clients while consuming data from legacy APIs | |
| 23 | + |
| 24 | +## Availability |
| 25 | + |
| 26 | +* GraphQL APIs are supported in all API Management service tiers |
| 27 | +* Pass-through and synthetic GraphQL APIs currently aren't supported in a self-hosted gateway |
| 28 | +* GraphQL subscription support in synthetic GraphQL APIs is currently in preview |
| 29 | + |
| 30 | +## What is GraphQL? |
| 31 | + |
| 32 | +GraphQL is an open-source, industry-standard query language for APIs. Unlike 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. |
| 33 | + |
| 34 | +The GraphQL specification explicitly solves common issues experienced by client web apps that rely on REST APIs: |
| 35 | + |
| 36 | +* It can take a large number of requests to fulfill the data needs for a single page |
| 37 | +* REST APIs often return more data than needed the page being rendered |
| 38 | +* The client app needs to poll to get new information |
| 39 | + |
| 40 | +Using a GraphQL API, the client app can specify the data they need to render a page in a query document that is sent as a single request to a GraphQL service. A client app can also subscribe to data updates pushed from the GraphQL service in real time. |
| 41 | + |
| 42 | +## Schema and operation types |
| 43 | + |
| 44 | +In API Management, add a GraphQL API from a GraphQL schema, either retrieved from a backend GraphQL API endpoint or uploaded by you. A GraphQL schema describes: |
| 45 | + |
| 46 | +* Data object types and fields that clients can request from a GraphQL API |
| 47 | +* Operation types allowed on the data, such as queries |
| 48 | + |
| 49 | +For example, a basic GraphQL schema for user data and a query for all users might look like: |
| 50 | + |
| 51 | +``` |
| 52 | +type Query { |
| 53 | + users: [User] |
| 54 | +} |
| 55 | +
|
| 56 | +type User { |
| 57 | + id: String! |
| 58 | + name: String! |
| 59 | +} |
| 60 | +``` |
| 61 | + |
| 62 | +API Management supports the following operation types in GraphQL schemas. For more information about these operation types, see the [GraphQL specification](https://spec.graphql.org/October2021/#sec-Subscription-Operation-Definitions). |
| 63 | + |
| 64 | +* **Query** - Fetches data, similar to a `GET` operation in REST |
| 65 | +* **Mutation** - Modifies server-side data, similar to a `PUT` or `PATCH` operation in REST |
| 66 | +* **Subscription** - Enables notifying subscribed clients in real time about changes to data on the GraphQL service |
| 67 | + |
| 68 | + For example, when data is modified via a GraphQL mutation, subscribed clients could be automatically notified about the change. |
| 69 | + |
| 70 | +> [!IMPORTANT] |
| 71 | +> API Management supports subscriptions implemented using the [graphql-ws](https://github.com/enisdenjo/graphql-ws) WebSocket protocol. Queries and mutations aren't supported over WebSocket. |
| 72 | +> |
| 73 | +
|
| 74 | +## Resolvers |
| 75 | + |
| 76 | +*Resolvers* take care of mapping the GraphQL schema to backend data, producing the data for each field in an object type. The data source could be an API, a database, or another service. For example, a resolver function would be responsible for returning data for the `users` query in the preceding example. |
| 77 | + |
| 78 | +In API Management, you can create a *custom resolver* to map a field in an object type to a backend data source. You configure resolvers for fields in synthetic GraphQL API schemas, but you can also configure them to override the default field resolvers used by pass-through GraphQL APIs. |
| 79 | + |
| 80 | +API Management currently supports HTTP-based resolvers to return the data for fields in a GraphQL schema. To use an HTTP-based resolver, configure a [`http-data-source`](http-data-source-policy.md) policy that transforms the API request (and optionally the response) into an HTTP request/response. |
| 81 | + |
| 82 | +For example, a resolver for the preceding `users` query might map to a `GET` operation in a backend REST API: |
| 83 | + |
| 84 | +```xml |
| 85 | +<http-data-source> |
| 86 | + <http-request> |
| 87 | + <set-method>GET</set-method> |
| 88 | + <set-url>https://myapi.contoso.com/api/users</set-url> |
| 89 | + </http-request> |
| 90 | +</http-data-source> |
| 91 | +``` |
| 92 | + |
| 93 | +## Manage GraphQL APIs |
| 94 | + |
| 95 | +* Secure GraphQL APIs by applying both existing access control policies and a [GraphQL validation policy](validate-graphql-request-policy.md) to secure and protect against GraphQL-specific attacks. |
| 96 | +* Explore the GraphQL schema and run test queries against the GraphQL APIs in the Azure and developer portals. |
| 97 | + |
| 98 | + |
| 99 | +## Next steps |
| 100 | + |
| 101 | +- [Import a GraphQL API](graphql-api.md) |
| 102 | +- [Import a GraphQL schema and set up field resolvers](graphql-schema-resolve-api.md) |
0 commit comments