How to make a graphql request for persisted queries using HttpGraphQlClient in spring graphql?

[giridhargg]

I have spring boot graphql server side and spring graphql client side applications. The client graphql queries are persisted in graphql-server-side. Now from the graphql-client-side application, how to make the graphql requests using the sha256 hash of the graphql query using HttpGraphQlClient?

I know that we pass the sha256 hash in the 'extensions' key of the request body. But to access RequestSpec's extensions() method, GraphQlClient contract exposes two methods RequestSpec document(String document) and RequestSpec documentName(String document). One way it to do is graphQlClient.document(null).extensions(Map.of(...)).executeSync(), but the parameter for document() method is not nullable so that doesn't work.

Basically, how to make a graphql request with the hash of a persisted query using HttpGraphQlClient? Or is this not supported yet?

[bclozel]

Thanks for reaching out, and sorry for the delayed reply. I saw that in the meantime, you got a workaround from a community member with an "" document.

I think that with persisted queries (PQ) and automatic persisted queries (APQ), there is enough material to consider them as a broader theme in Spring for GraphQL. On the server side, GraphQL Java has a PreparsedDocumentProvider that is a key component for such support.

This issue is about the client side support, and the GraphQlClient should be usable against all GraphQL applications. I guess there are several interesting features in PQ and APQL - is there one particular aspect that you are using?

• saving the cost of parsing and validation on the server
• lighter HTTP requests
• HTTP caching (although this would require GET requests)
• security: only allow queries that are predefined

Are you using APQL or is your client given a manifest with allowed queries?

Here are a few things we should consider here:

1. supporting PersistedQueryNotFound and PersistedQueryNotSupported errors
2. considering an interceptor that would use query ids automatically
3. client could load manifests to check whether the query id exists before sending

We are quite early in the process and this would probably materialize in a future feature release. The more you can share with us about your scenario the better we can consider our options.

Thanks!

[giridhargg]

No problem, and sorry I didn’t provide enough context earlier.

To clarify the setup and constraints:

• We do not control the GraphQL server. It already supports persisted queries and expects the request to contain only the SHA-256 hash under extensions.persistedQuery, with the query field either absent or null.
• Sending an empty string ("") as the document does not work for us — the server returns a persisted query hash mismatch error. Sending query: null (or omitting the field entirely) works correctly.
• This is why the current workaround of document("") is not viable in our case, and why we’re looking for a first-class client-side solution.

On the client side, we are currently using persisted queries primarily for:

• Saving parsing and validation cost on the server
• Lighter HTTP payloads
• Security: only pre-registered queries are allowed

We may move to GET requests later for HTTP caching, but for now this is strictly POST-based.

Regarding your question:
> Are you using APQ or is your client given a manifest with allowed queries?
We are closer to the latter. All queries are pre-registered and stored in a private query store, and the client only knows the operation name → hash mapping. We are not doing APQ-style retry with the full document.

We are using HttpGraphQlClient with WebClient underneath backed by Netty (ReactorClientHttpConnector). So technically, the only workaround would be to add a WebClient filter or interceptor that mutates the request body and strips the query field. However, manipulating the request body at that level feels brittle and error-prone, especially when dealing with reactive streams.

What would really help on the client side (conceptually) is one of the following:

• First-class support for persisted queries / APQ in GraphQlClient
• A way to create a RequestSpec that does not require a document
• Or a dedicated API for supplying a query id / hash instead of a query string
• Possibly an interceptor or strategy hook specifically designed for PQ/APQ handling

I agree that PQ/APQ is a broader topic and probably deserves dedicated client-side support, especially considering:

• handling PersistedQueryNotFound / PersistedQueryNotSupported
• automatic hash-based requests
• optional fallback behavior
• manifest-based validation on the client

Thanks again for taking a look at this — it would be great to see this materialize as a future feature in Spring for GraphQL.

[giridhargg]

Hi, given this is being addressed, I just wanted to check a few things regarding persisted queries:

• Do you intend to define a standard resource layout, similar to how GraphQL schemas are conventionally placed under src/main/resources/graphql/? For example, would there be a recommended location for persisted query documents?
• Would Spring GraphQL define a recommended file extension for persisted query documents? Since schema files and operation documents are both GraphQL SDL, is there a preferred extension (e.g. .graphql, .gql) to distinguish persisted operation documents from schema files?
• Would Spring GraphQL define a manifest format describing persisted queries? If so, would it be a Spring-specific format (for example, YAML or .properties), or would it adopt an existing industry format?
• Has the team considered adopting Apollo's persisted query manifest format (persisted-query-manifest.json) as the standard representation? Apollo already defines a JSON manifest containing operation IDs (hashes), operation bodies, names, and types: link. If Spring GraphQL adds persisted query support, would you expect it to consume this manifest directly for interoperability, or would Spring define its own manifest format?
• If Spring were to define its own convention, what would you expect it to standardize?
  • Resource location?
  • Manifest filename?
  • Manifest structure?
  • Document naming conventions?
  • Build-time validation and hash generation?
• Would Spring Boot auto-configuration be expected to load these resources automatically (similar to schema loading), or would persisted query support intentionally remain an application concern?

I'm working on a Spring Boot GraphQL library for client side applications and would like to follow any conventions that the Spring GraphQL team either already recommends or intends to establish in the future, rather than inventing a separate ecosystem.