Retrieve a GraphQL Schema¶

🕵️ Enable Introspection¶

Enabling Introspection on Your Application¶

Using Apollo¶

When creating a new instance of the ApolloServer, you have to provide an object describing your resolvers and type definitions. This object can also include an introspection parameter.

const server = new ApolloServer({
  typeDefs,
  resolvers,
  introspection: true,
})

This option is documented in the ApolloServer reference

Fine-tuning¶

Using Apollo plugins, you can also have better access control over this query. Here is an example of a plugin that prevents access to the introspection query if the request does not feature the CLI header.

const introspectionPlugin = {
  requestDidStart() {
    return {
      async willSendResponse(requestContext) {
        const { request, response } = requestContext;

        if (request.http.headers.get('x-cli-access') !== 'true') {
          if (request.operationName === 'IntrospectionQuery') {
            response.data = null;
            response.errors = [
              {
                message: 'Introspection query not allowed',
                extensions: {
                  code: 'FORBIDDEN'
                }
              }
            ];
          }
        }
      }
    };
  }
}

Retrieving the Schema¶

You can retrieve the GraphQL schema using various methods:

Using cURL¶

curl --location 'https://example.com/graphql' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"query":"query IntrospectionQuery { __schema { queryType { name } mutationType { name } subscriptionType { name } types { ...FullType } directives { name description locations args { ...InputValue } } } } fragment FullType on __Type { kind name description fields(includeDeprecated: true) { name description args { ...InputValue } type { ...TypeRef } isDeprecated deprecationReason } inputFields { ...InputValue } interfaces { ...TypeRef } enumValues(includeDeprecated: true) { name description isDeprecated deprecationReason } possibleTypes { ...TypeRef } } fragment InputValue on __InputValue { name description type { ...TypeRef } defaultValue } fragment TypeRef on __Type { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } } } } } ","variables":{}}' \
> introspection.json

REST¶

Escape is compatible with:

• Swagger v2
• OpenAPI v3
• Postman Collections

More input sources will be available soon, including the ability to scan undocumented APIs.

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¶

The configuration for persisted queries is 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