Skip to content
Prev Previous commit
Next Next commit
Started work on the response structure
  • Loading branch information
michaelstaib committed Aug 29, 2024
commit e7b37d99e17223f3a02a2f088dea8e28b38a967e
20 changes: 20 additions & 0 deletions spec/Appendix B -- Variable Batching.md
Original file line number Diff line number Diff line change
@@ -137,3 +137,23 @@ And the body:
]
}
```

### Response

When a server receives a well-formed _variable batching request_, it MUST return a well‐formed stream of _GraphQL responses_. Each response in the stream corresponds to the result of validating and executing the requested operation with one set of variables. The server's response stream describes the outcome of each operation, including any errors encountered during the execution of the request.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should use the word "stream" here. I think "list" is fine; I think the default media type would likely be e.g. application/graphql-response-list+json (a JSON array of GraphQL responses) but application/jsonl would allow for easier early parsing of responses when the client is stream-capable.


A server must comply with [RFC7231](https://datatracker.ietf.org/doc/html/rfc7231).

Each response in the stream follows the standard GraphQL response format, with the addition of a required `variableIndex` field at the top level of each response. The `variableIndex` indicates the index of the variables map from the original request, allowing the client to associate each response with the correct set of variables.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The definition of the application/graphql-response type should be modified such that other keys are allowed iff they are specified as part of a specification or appendix hosted under the graphql.org domain; then this spec can "extend" that type with these keys. May want to go a slightly different direction on this in future.


**Note:** The server MAY respond with results in any order. The `variableIndex` field ensures that clients can correctly match each response to its corresponding set of variables, regardless of the order in which the responses are returned.

#### Response Structure

Each line in the JSON Lines (JSONL) response MUST include the following fields:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The combination of MUST and optional is confusing. I would change this to something more along the lines of "in addition to the regular fields expected on a GraphQL response, each entry in a variable batching response MUST include the variableIndex field..."


- **`variableIndex`** (Required, integer): The index of the corresponding variables map from the original request's `variables` array. This allows clients to match each response with the correct set of variables.
- **`data`** (Optional, map): The data resulting from the execution of the GraphQL operation with the corresponding set of variables.
- **`errors`** (Optional, array): An array of errors, if any were encountered during the execution of the operation.
- **`extensions`** (Optional, map): A map that MAY include additional information about the request and execution, as needed by implementors.
-
Loading
Oops, something went wrong.