Using GraphQL

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

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

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

Note: For application/json payloads of the form

{
"query": "...",
"operationName": "...",
"variables": { "myVariable": "someValue", ... }
}

Apigee currently ignores the optional operationName and variables fields.

For a quick summary of the options for the GraphQL policy, see GraphQL options below.

To learn more about GraphQL, see GraphQL.org.

Example

The following example shows how to upload a GraphQL schema to Apigee, and use it to validate requests with GraphQL content.

Caution: Verifying the payload against the schema is generally an expensive operation, and we recommend choosing to perform schema validation with care. Schema validation operations can be CPU intensive, especially when the payload and the schema are complex, and can result in significant latencies.

Note: You can only provide one schema per policy. If you need to include multiple schemas, add multiple GraphQL policies to your proxy.

Notes: For the classic Proxy Editor only:

• You can only upload a GraphQL schema file when you add a GraphQL policy. You cannot upload it in the Resources pane in the Proxy Editor.
• After uploading a GraphQL schema file, you cannot view or edit it in the Proxy Editor.

These limitations do not apply to the new Proxy Editor.

Create a schema file

To run the example, first create a GraphQL schema file with the following contents:

type Query {
  allPersons(last: Int): [Person!]!
}

type Mutation {
  createPerson(name: String!, age: Int!): Person!
}

type Subscription {
  newPerson: Person!
}

type Person {
  name: String!
  sex: String!
  age: Int!
  posts: [Post!]!
}

type Post {
  title: String!
  author: Person!
}

Save the file with whatever name you'd like to use, followed by the extension .graphql.

Add the GraphQL policy in the Apigee UI

Note: Apigee is introducing a new version of the Proxy Editor, which will make it easier to manage proxies.

The instructions in the first two tabs below explain how to use either the new Proxy Editor or the classic Proxy Editor.

New Proxy Editor

First, create the GraphQL policy as follows:

1. Sign in to the Apigee UI.
2. In the navigation bar, select Develop > API Proxies.
3. In the list of proxies, select the API proxy for which you want to use the GraphQL policy.
4. Click the DEVELOP tab.
5. In the left-hand pane, click the + button next to the Policies folder.

6. In the Create policy dialog, click in the Select policy type field and scroll down to Mediation and select GraphQL.

   

   Enter a Display name and Name.

   Next, select a GraphQL schema file as follows:

   1. Click the Schema File field. This displays the following choices:
      • No Schema. If you select this option, Apigee will not use a schema to validate requests.
      • Import GraphQL schema (.graphql)

   2. Select Import GraphQL schema (.graphql). This displays the following:

      

   3. Click Choose File and select the schema file you created previously (which must have the extension .graphql). The file appears in the Schema name field.

      
7. Click Create to create the policy.

Now that you have created the GraphQL policy, you can attach it to a step in the PreFlow:

1. Select Proxy Endpoints > default > PreFlow in the left-hand pane:

   

2. Click the + button next to PreFlow in the Response pane at the bottom-right of the Visual Editor:

   

3. In the Add policy step dialog, select the GQL- policy.
   Note:This example uses the default name, GQL, for the GraphQL policy. You can change the name in the DisplayName element in the XML for the policy, by adding a descriptive phrase after GQL-. See Change the policy name.
4. Click Add to attach the policy.
5. Click Save to save the current revision with your changes.
6. To deploy your changes, click the Overview tab and select Deploy.

See GraphQL options below for the options you can set for the GraphQL policy.

Classic Proxy Editor

1. Sign in to the Apigee UI.
2. In the navigation bar, select Develop > API Proxies.
3. In the list of proxies, select the API proxy for which you want to use the GraphQL policy.
4. Click the DEVELOP tab.

5. In the Flow: PreFlow pane, click the + Step button.

   

6. In the Add Step pane, scroll down to the bottom of the Mediation section, and select GraphQL.

   

   The Add Step pane displays the following options:

   • Display Name: Display name of the policy.
   • Name: Internal name of the policy.
   • Schema file: Option to upload a file containing a GraphQL schema that Apigee will use to validate requests with GraphQL content.

   To use a schema, do the following:

   1. Click the Schema File field. This displays the following choices:
      • No Schema. If you select this option, Apigee will not use a schema to validate requests.
      • Import GraphQL schema (.graphql)

   2. Select Import GraphQL schema (.graphql). This displays the following:

      

   3. Click Choose File and select the schema file you created previously (which must have the extension .graphql). The file appears in the Schema name field.

      

7. Click Add. The Flow: PreFlow pane now appears as shown below:

   

   See GraphQL options below for the options you can set for the GraphQL policy. For this example, leave them as they are.

8. To deploy your proxy, click the Overview tab and select Deploy.

   

Now you can test the GraphQL policy with the following curl command:

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query query_name {allPersons {name}}' -k

Where PROXY_BASEPATH is the proxy basepath and HOST_NAME is the name of your proxy, including the latest revision number. When you run the command, Apigee validates the request against the schema and returns the following output.

{
  "query query_name {allPersons {name}}": "",
  "id": 101
}

Here's another example of a request:

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query ilovegql {DEADBEEF}' -k

This time the request validation fails with the following error message.

{"fault":{"faultstring":"steps.graphQL.SchemaValidationFailed","detail":{"errorcode":"steps.graphQL.SchemaValidationFailed"}}}

GraphQL options

The GraphPolicy has the following options:

• OperationType: The operation type. The options are:
  • query: The GraphQL equivalent of the REST GET operation.
  • mutation: The GraphQL equivalent of the REST PUT operation.
  • query_mutation: Both query and mutation.
• 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.
• 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 into smaller payloads.
• Action: One the following GraphQL actions:
  • parseApigee parses the GraphQL payload into the flow variables. You can then use the contents of the flow variables in policies such as JavaCallout. Note that parse also verifies the payload.
  • verify: Apigee verifies that the GraphQL payload conforms to the schema uploaded to the proxy. You can use verify to ensure that you do not get requests that don't conform to your schema. This can save valuable CPU time in the backend.
  • parse_verify: Parse and verify the payload.
• ResourceURL: The path to the GraphQL schema file that Apigee uses to verify the GraphQL request.`

To learn more about these options, see the GraphQL policy reference page.