Azure API Management policies for GraphQL APIs

This article provides a reference for API Management policies to validate and resolve queries to GraphQL APIs.

More information about policies:

GraphQL API policies

Validate GraphQL request

The validate-graphql-request policy validates the GraphQL request and authorizes access to specific query paths. An invalid query is a “request error”. Authorization is only done for valid requests.

Permissions
Because GraphQL queries use a flattened schema:

• Permissions may be applied at any leaf node of an output type:
  • Mutation, query, or subscription
  • Individual field in a type declaration.
• Permissions may not be applied to:
  • Input types
  • Fragments
  • Unions
  • Interfaces
  • The schema element

Authorize element
Configure the authorize element to set an appropriate authorization rule for one or more paths.

• Each rule can optionally provide a different action.
• Use policy expressions to specify conditional actions.

Introspection system
The policy for path=/__* is the introspection system. You can use it to reject introspection requests (__schema, __type, etc.).

Policy statement

<validate-graphql-request error-variable-name="variable name" max-size="size in bytes" max-depth="query depth">
    <authorize>
        <rule path="query path, for example: '/listUsers' or '/__*'" action="string or policy expression that evaluates to 'allow|remove|reject|ignore'" />
    </authorize>
</validate-graphql-request>

Example: Query validation

This example applies the following validation and authorization rules to a GraphQL query:

• Requests larger than 100 kb or with query depth greater than 4 are rejected.
• Requests to the introspection system are rejected.
• The /Missions/name field is removed from requests containing more than two headers.

<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4"> 
    <authorize>
        <rule path="/__*" action="reject" /> 
        <rule path="/Missions/name" action="@(context.Request.Headers.Count > 2 ? "remove" : "allow")" />
    </authorize>
</validate-graphql-request> 

Example: Mutation validation

This example applies the following validation and authorization rules to a GraphQL mutation:

• Requests larger than 100 kb or with query depth greater than 4 are rejected.
• Requests to mutate the deleteUser field are denied except when the request is from IP address 198.51.100.1.

<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4"> 
    <authorize>
        <rule path="/Mutation/deleteUser" action="@(context.Request.IpAddress <> "198.51.100.1" ? "deny" : "allow")" />
    </authorize>
</validate-graphql-request> 

Elements

Attributes

Request actions

Available actions are described in the following table.

Error handling

Failure to validate against the GraphQL schema, or a failure for the request’s size or depth, is a request error and results in the request being failed with an errors block (but no data block).

Similar to the Context.LastError property, all GraphQL validation errors are automatically propagated in the GraphQLErrors variable. If the errors need to be propagated separately, you can specify an error variable name. Errors are pushed onto the error variable and the GraphQLErrors variable.

Usage

This policy can be used in the following policy sections and scopes.

Set GraphQL resolver

The set-graphql-resolver policy retrieves or sets data for a GraphQL field in an object type specified in a GraphQL schema. The schema must be imported to API Management. Currently the data must be resolved using an HTTP-based data source (REST or SOAP API).

• This policy is invoked only when a matching GraphQL query is executed.
• The policy resolves data for a single field. To resolve data for multiple fields, configure multiple occurrences of this policy in a policy definition.
• The context for the HTTP request and HTTP response (if specified) differs from the context for the original gateway API request:
  • The HTTP request context contains arguments that are passed in the GraphQL query as its body.
  • The HTTP response context is the response from the independent HTTP call made by the resolver, not the context for the complete response for the gateway request.

Policy statement

<set-graphql-resolver parent-type="type" field="field"> 
    <http-data-source> 
        <http-request> 
            <set-method>HTTP method</set-method> 
            <set-url>URL</set-url>
            [...]  
        </http-request> 
        <http-response>
            [...]
        </http-response>
      </http-data-source> 
</set-graphql-resolver> 

Examples

Resolver for GraphQL query

The following example resolves a query by making an HTTP GET call to a backend data source.

Example schema

type Query {
    users: [User]
}

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

Example policy

<set-graphql-resolver parent-type="Query" field="users">
    <http-data-source>
        <http-request>
            <set-method>GET</set-method>
            <set-url>https://data.contoso.com/get/users</set-url>
        </http-request>
    </http-data-source>
</set-graphql-resolver>

Resolver for a GraqhQL query that returns a list, using a liquid template

The following example uses a liquid template, supported for use in the set-body policy, to return a list in the HTTP response to a query.

Example schema

type Query {
    users: [User]
}

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

Example policy

<set-graphql-resolver parent-type="Query" field="users">
    <http-data-source>
        <http-request>
            <set-method>GET</set-method>
            <set-url>https://data.contoso.com/users</set-url>
        </http-request>
        <http-response>
            <set-body template="liquid">
                [
                    {% JSONArrayFor elem in body %}
                        {
                            "name": "{{elem.title}}"
                        }
                    {% endJSONArrayFor %}
                ]
            </set-body>
        </http-response>
    </http-data-source>
</set-graphql-resolver>

Resolver for GraphQL mutation

The following example resolves a mutation that inserts data by making a POST request to an HTTP data source. The policy expression in the set-body policy of the HTTP request modifies a name argument that is passed in the GraphQL query as its body.

Example schema

type Query {
    users: [User]
}

type Mutation {
    makeUser(name: String!): User
}

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

Example policy

<set-graphql-resolver parent-type="Mutation" field="makeUser">
    <http-data-source>
        <http-request>
            <set-method>POST</set-method>
            <set-url> https://data.contoso.com/user/create </set-url>
            <set-header name="Content-Type" exists-action="override">
                <value>application/json</value>
            </set-header>
            <set-body>@{
                var body = context.Request.Body.As<JObject>(true);  
                JObject jsonObject = new JObject();
                jsonObject.Add("name", body["name"])
                return jsonObject.ToString();
            }</set-body>
        </http-request>
    </http-data-source>
</set-graphql-resolver>

Elements

Attributes

Usage

This policy can be used in the following policy sections and scopes.

Next steps

For more information about working with policies, see: