Import a GraphQL API (preview)

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.

API Management tackles the security, authentication, and authorization challenges that come with publishing GraphQL APIs. Using API Management to expose your GraphQL APIs, you can:

  • Add a GraphQL service as APIs via Azure portal.
  • Secure GraphQL APIs by applying both existing access control policies and a new 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.

Important

API Management GraphQL API is currently in preview.

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.

Prerequisites

Add a GraphQL API

  1. Navigate to your API Management instance.

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

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

    Selecting GraphQL icon from list of APIs

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

    Demonstrate fields for creating GraphQL

    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.
    For example: https://example.com/your-GraphQL-name. You can also use the common "Star Wars" GraphQL endpoint as a demo.
    Upload schema file Select to browse and upload your schema file.
    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 version control your GraphQL API.

  5. Click Create.

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.

      Demonstrating adding fields to the query editor

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

  9. Click Send.

  10. View the Response.

    View the test query response

  11. Repeat preceding steps to test different payloads.

  12. When testing is complete, exit test console.

Limitations

  • Only GraphQL pass through is supported.
  • A single GraphQL API in API Management corresponds to only a single GraphQL backend endpoint.

Next steps

Transform and protect a published API