hasNext field on GraphQL responses

[robrichard]

Context

GraphQL clients may need to know if additional payloads will be sent by the server. Relay/Facebook used a is_final field in extensions for this.

Decision

• The spec proposal introduces a field hasNext, which is present on all payloads when more than one payload will be sent. The final payload will contain hasNext: false, all others will contain hasNext: true.
• hasNext: true indicates that there will be an additional response, not necessarily additional data. An empty payload with hasNext: true is valid and will be sent when the final payload is from a streamed field where it is not known synchronously if more data is present.
• When defer/stream is used on subscriptions hasNext: false indicates that the payload is the final result from an individual source stream event.

Consequences

• Facebook recommended inverting the meaning from their is_final field due to issues they ran into: clients that were expecting is_final would fail when connecting to servers that did not support it.
• We chose to use a field directly on the payload instead of relying on out of band signals from the underlying transport mechanism to ensure compatibility amongst clients and to support defer/stream on subscriptions.

Status

• defined in spec
• implemented in graphql-js

[yaacovCR]

Linking to #54 (reply in thread)

Generally, I think this discussion should be reopened now that the graphql-over-http specification has matured and we can rely on a more robust transport specification to manage the concerns mentioned above.

As mentioned at the link:

What practical advantages does dropping hasNext have?

1. Saves bytes, bandwith, time, energy.
2. Provides clean separation between abstract "results" and the method by which they are delivered.
3. Paves the way for transport protocols to experiment with communicating backpressure. If separately streamed fields are multiplexed using a streamId, the client can request the additional stream payloads it needs, rather than all available streamed payloads in the order that they complete.

[robrichard]

Many GraphQL clients like Apollo and Relay use a pluggable network layer, allowing them to be completely transport agnostic. Developers using these clients can write their own integration for their transport or use an existing network layer. These clients need to know the information that the hasNext field provides. See Relay's usage of is_final (the original name for this field).

If we removed hasNext from the GraphQL spec, clients would not have a standardized field they can rely on. Instead, each client would have to define how this information is provided, (either using non-standard extensions as Relay did, or some other means), and each network layer would have to implement a translation from their specific transport to what the client expects.

Paves the way for transport protocols to experiment with communicating backpressure. If separately streamed fields are multiplexed using a streamId, the client can request the additional stream payloads it needs, rather than all available streamed payloads in the order that they complete.

I don't see how the presence of the hasNext field blocks this type of experimentation?

[yaacovCR]

If we removed hasNext from the GraphQL spec, clients would not have a standardized field they can rely on. Instead, each client would have to define how this information is provided, (either using non-standard extensions as Relay did, or some other means), and each network layer would have to implement a translation from their specific transport to what the client expects.

Yup, and I think that's exactly what we should do. Creating a transport agnostic client/server really should be the job of the transport/client/server. It is not necessary to pollute the data itself, and so should not do so -- in my opinion. :)