hasNext on single response results

[robrichard]

Context

With the introduction of the @defer and @stream directives we have a new top level response field called hasNext (see #5). This field will be mandatory when GraphQL sends multiple responses as a result of @defer and @stream.

The purpose of this discussion is to determine what the behavior of hasNext should be when the server sends only a single response, i.e. nothing is deferred or streamed.

Currently, the spec proposal says:

This entry is not required for GraphQL operations that return a single response map.

GraphQL-JS also currently does not return hasNext when the execution result is only a single response.

@IvanGoncharov has proposed that going forward GraphQL servers should always return hasNext: false when the execution result is only a single response, to have a more stable shape of responses overall. We would change the spec text to more strongly encourage servers to return hasNext on all responses. But since servers that implement an older version of the spec will not send hasNext, we should ensure the spec is clear that clients do not rely on its presence.

For example:

// Wrong, client will be expecting more payloads if server does not return hasNext
if (response.hasNext !== false) { 
  // assume more payloads

// Correct, client will not expect more payloads if server does not return hasNext
if (response.hasNext) { 
  // assume more payloads

Decision

We discussed this at the October WG and the general consensus is that we should require that hasNext be omitted on single responses. The referenced line in the spec has been updated to

This entry must not be present for GraphQL operations that return a single response map.

[benjie]

We discussed this at the October WG and the general consensus is that we should require that hasNext be omitted on single responses.

[michaelstaib]

Just to be clear ...

• do we require servers to send hasNext even if they do not support the defer part?
• do we require servers to send hasNext even if there is now defer involved in the request?

[robrichard]

Spec pr has been updated to reflect that hasNext must be omitted on single responses.

• hasNext must be sent when there will be more than one response
• hasNext must not be sent when there will be only one response - this is compatible with existing servers that do not support defer/stream