GraphQL Persisted Queries

Overview¶

Persisted queries are a mechanism to improve the performance and security of GraphQL APIs. By storing (or persisting) the queries on the server, clients can refer to these queries using a unique identifier instead of sending the entire query string. This reduces the payload size, minimizes parsing overhead, and helps prevent certain types of attacks, such as query injection.

If persisted queries are enabled on your server, Escape cannot scan your API by default as it doesn't know the persisted queries' hashes. You need to configure your application to allow Escape to scan it.

Configuring the Application¶

As this feature is currently in beta, the configuration is only available on the Expert tab of your application.

Go to your application page, then go to Settings (top right corner) and click on the Expert tab (on the left).

To add the persisted queries, you have two options:

Option 1: External URL Reference¶

If you have a large number of queries, refer to an external URL containing your persisted queries:

internal:
  graphql_persisted_queries_url: https://example.com/path/to/persisted-queries.json

Escape will retrieve and parse the JSON object from the specified URL.

Option 2: Direct Configuration¶

For a small number of queries, add the persisted queries directly in the configuration:

internal:
  graphql_persisted_queries_raw: >
    {
      "86f01e23de1c770cabbc35b2d87f2e5fd7557b6f": "query HelloQuery { hello }",
      "c59d86fc8f3c9617a5aacc7f22c04d539b8e6c46": "..."
    }

Supported Formats¶

Persisted queries can be provided in two formats:

1. Apollo Persisted Queries Manifest Format
2. Yoga Persisted Queries Format
3. Hive Persisted Operations Format