GraphQL policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

What

The GraphQL policy can parse GraphQL payloads into message flow variables, verify GraphQL requests against a schema, or both.

You can use the GraphQL policy to:

• Ensure that your APIs only process requests that conform to the schema you provide.
• Impose restrictions on the payload by setting a maximum on the number of fragments allowed.
• Associate GraphQL with API products.
• Leverage the Oauth2, VerifyAPIKey, and Quota policy features, just as in REST.

GraphQL supports the following types of payloads:

• POST of graphQL payloads with Content-Type : application/graphql
• POST of graphQL payloads with Content-Type: applcation/json
• GET of graphQL payloads where the payload is a query parameter

For more information, see the following resources:

• Introduction to GraphQL
• Queries and Mutations
• Flow variables reference

This policy is a Standard policy and can be deployed to any environment type. For information on policy types and availability with each environment type, see Policy types.

See Using GraphQL for an example that uses this policy.

<GraphQL> element

Defines a <GraphQL> policy.

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
  <OperationType>[query|mutuation|all]</OperationType>
  <MaxDepth>MAX_DEPTH</MaxDepth>
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
  // [Start maxpayloadsize]
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL>PATH/TO/SCHEMA.xsd</ResourceURL>
</GraphQL>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GraphQL name="GraphQLParser">
  <Source>request</Source>
  <OperationType>query</OperationType>
  <MaxDepth>10</MaxDepth>
  <MaxCount>10</MaxCount>
  <MaxPayloadSizeInBytes></MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL></ResourceURL>
</GraphQL>

This element has the following attributes that are common to all policies:

The following table provides a high-level description of the child elements of <GraphQL>:

Each of these child elements is described in the sections that follow.

Child element reference

This section describes the child elements of <GraphQL>.

<Action>

Action represents one of the following GraphQL actions:

• parse: Apigee parses the GraphQL payload into message flow variables. See Examples of message flow variable representations for an explanation of the variables that are set when Action is set to parse. This can save valuable CPU time in the backend. Note that verify also parses the payload.
• verify: Apigee verifies that the GraphQL payload conforms to the schema uploaded to the proxy.
• parse_verify: Apigee parses and verifies the GraphQL request.

The <Action> element uses the following syntax:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Action>parse</Action>
</GraphQL>

<MaxCount>

The maximum number of fragments that can be in the payload. You can use this to prevent the GraphQL back-end server of the customer from executing highly complex queries, forcing clients to break their logic in to smaller payloads.

The <MaxCount> element uses the following syntax:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
</GraphQL>

<MaxDepth>

The maximum depth of the query, when represented as a tree. MaxDepth allows you to block deep queries in the payload, so that Apigee does not need to create very large flow variables to hold the values. However, the payload is sent as is, regardless of the value of MaxDepth. The default value is 10.

The <MaxDepth> element uses the following syntax:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxDepth>MAX_DEPTH</MaxDepth>
</GraphQL>

<MaxPayloadSizeInBytes>

The maximum size of a payload in kilobytes. You can use this to limit the payload size, to avoid performance issues.

Note: If MaxPayloadSizeInByte is not provided in the policy, no size restriction is enforced.

The <MaxPayloadSizeInBytes> element uses the following syntax:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
</GraphQL>

<OperationType>

Indicates the type of request that can be parsed:

• query: A GraphQL query.
• mutation: A GraphQL mutation
• query_mutation: A GraphQL query or a mutation.

If the scope is query, and a mutation request is passed, the request fails and returns a 4xx error.

The <OperationType> element uses the following syntax:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <OperationType>[query|mutation|query_mutation]</OperationType>
</GraphQL>

<ResourceURL>

The path to the GraphQL schema file that the GraphQL policy verifies requests against. See Example for an example of uploading a GraphQL schema to Apigee.

If the name of your uploaded schema file is my-schema.graphql, then the <ResourceURL> element would be

<ResourceURL>graphql://my-schema.graphql</ResourceURL>

The ResourceURL element uses the following syntax:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <ResourceURL>PATH/TO/SCHEMA.graphql</ResourceURL>
</GraphQL>

<Source>

Source on which this policy executes.

The <Source> element uses the following syntax:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
</GraphQL>

GraphQL Parser

The graphQL parser supports all features of a graphQL query and represents it as a graph in the message flow dotted notation. A query can comprise of operation definition and optionally fragments identified as fragment definitions. See the GraphQL specification.

Anatomy of a graphQL request

The diagram below shows the anatomy of a graphQL request.

Representation in message flow of operation definitions

The parser implementation covers all aspects of graphQL syntax, including support for query and mutations. See Message flow variable.

The message flow variables follows this convention:

graphql.(root-index).(root definition)[(sub-indices).(child-definitions)…]

where:

• graphql: Static prefix indicating this is graphQL related message flow variables
• root-Index: based index indicating the root level query definitions index (default up to 4 per request)
• root-definition: Root level graphQL request message body, args, its values
• sub-indices: Child indices
• child-definitions: Leaf level definitions that correlate to specific fields and its values

Representation in message flow variable of operation definitions

Representation in message flow of fragment definitions

Examples of message flow variable representations

The following examples show the message flow variable representations for sample request payloads.

{
 employee(id: 123) {
   id
   firstName
   lastName
 }
}

query Characters($episode: Episode, $withFriends: Boolean!) {
   friends @include(if: $withFriends) {
     friendsName
    }
}

query getUsers {
  admins: users(role: ADMIN) {
    lastName
  }
  accountants: users(role: ACCOUNTANT) {
    firstName
  }
}

Related topics

Using GraphQL