Console
Start free

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 parses GraphQL payloads into message flow variables, verifies GraphQL requests against a schema, or both.

Use the GraphQL policy to:

GraphQL supports the following types of payloads:

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.

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

First, create the GraphQL policy as follows:

  1. In the Apigee UI, go to the Proxy development > API Proxies page.

    Go to API Proxies

  2. In the list of proxies, select the API proxy for which you want to use the GraphQL policy.
  3. Click the Develop tab.
  4. In the left-hand pane, click the + button next to the Policies folder.

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

    GraphQL Create Policy dialog.

    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:

      Choose a schema file.

    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.

      Schema selected.
  6. 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:

    Target endpoints for PreFlow select in the Proxy Explorer.

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

    Click + button next to PreFlow in the Response pane.

  3. In the Add policy step dialog, select the GQL- policy.
  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.

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:

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