Add a synthetic GraphQL API and set up field resolvers

  • Article

APPLIES TO: All API Management tiers

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.

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 WebSocket protocol. Queries and mutations are not supported over WebSocket.

In this article, you'll:

  • Import a GraphQL schema to your API Management instance
  • 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.

Prerequisites

  • An existing API Management instance. Create one if you haven't already.
  • A valid GraphQL schema file with the .graphql extension.
  • A backend GraphQL endpoint is optional for this scenario.

Go to your API Management instance

  1. In the Azure portal, search for and select API Management services.

    Select API Management services

  2. On the API Management services page, select your API Management instance.

    Select your API Management instance

Add a GraphQL schema

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

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

    Screenshot of selecting GraphQL icon from list of APIs.

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

    Screenshot of fields for creating a GraphQL API.

    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 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.
    Version this API? Select to apply a versioning scheme to your GraphQL API.

  4. Select Create.

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

Configure resolver

Configure a resolver to map a field in the schema to an existing HTTP endpoint. High level steps are provided here. For details, see Configure a GraphQL resolver.

Suppose you imported the following basic GraphQL schema and wanted to set up a resolver for the users query.

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

  1. From the side navigation menu, under the APIs section, select APIs > your GraphQL API.

  2. On the Schema 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 the left margin, hover the pointer.

    2. Select + Add Resolver

      Screenshot of adding a GraphQL resolver in the portal.

  3. On the Create Resolver page:

    1. Update the Name property if you want to, optionally enter a Description, and confirm or update the Type and Field selections.
    2. In Data source, select HTTP API.

  4. 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 making a GET call to an existing HTTP data source.

        <http-data-source>
        <http-request>
            <set-method>GET</set-method>
            <set-url>https://myapi.contoso.com/users</set-url>
        </http-request>
    </http-data-source>

    Screenshot of configuring resolver policy in the portal.

  5. Select Create.

  6. To resolve data for another field in the schema, repeat the preceding steps to create a resolver.

Tip

As you edit a resolver policy, select Run Test to check the output from the data source, which you can validate against the schema. If errors occur, the response includes troubleshooting information.

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.

      Screenshot of adding fields to the query editor.

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

  9. Select Send.

  10. View the Response.

    Screenshot of viewing the test query response.

  11. Repeat preceding steps to test different payloads.

  12. 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.

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.

Next steps

Transform and protect a published API