When a GraphQL server receives a request, it must return a well‐formed response. Response describes the result of executing the requested operation if successful, and describes any errors encountered during the request.
A response to a GraphQL operation is in the format of JSON structure.
Response always consists of three main parts: extensions, errors and data:
In general GraphQL specification, extension entry is reserved for implementors to extend the protocol however they see fit, and hence there are no additional restrictions on its content. Information displayed in extensions is not necessarily related to the GraphQL itself. As it is highly customizable, it is perfect feature for developing different solutions for different user needs. For example, extensions could be configured in no-time to return Date&Time the query had executed and execution time in ms, all neatly organized into JSON structure. MIP currently does not provide this implementation, but we are open to disscussing it depending on the users needs.
If the operation encountered any errors, the response contains a map with listed errors. The value of this entry is described in the errors section. If the operation completed without encountering any errors, this entry is not present and simply has the value of null.
If there is data present, it means that the execution was successfull and errors map must be null. If the operation failed before execution, due to a syntax error, missing information, validation error or other type of error, this entry is not present and errors map is populated instead.
To ensure future changes to the protocol do not break existing servers and clients, response will never contain any entries other than the three described above.
Extensions and Errors section will always appear before data, just to make it more clear if the errors are present or not.
JSON is the most common serialization format in the world and so it is used in GraphQL also.
Map, List, String and also GraphQL scalar types: Boolean, Int, Float, Enum ValueWhen using JSON as a serialization of GraphQL responses, the following JSON values will be used to encode the related GraphQL values:
| GRAPHQL VALUE | JSON VALUE | ||
|---|---|---|---|
| Map | Object |
||
| List | Array |
||
| Null | Null |
||
| String | String |
||
| Boolean | True or False |
||
| Integer | Number |
||
| Float | Number |
||
| Enum | String |
Since the result of evaluating a selection set is ordered, the serialized Map of results preserves this order by writing the map entries in the same order as those fields were requested as defined by query execution
When writing the query, fields that we are requesting are put in some order. Results map will preserve this order by writing the map entries in the same order as those fields were requested as defined by query execution. Producing a serialized response where fields are represented in the same order in which they appear in the request improves human readability during debugging and enables more efficient parsing of responses if the order of properties can be anticipated.
Serialization formats which represent an ordered map will preserve the order of requested fields as defined by CollectFields() in the general GraphQL specification. Serialization formats which only represent unordered maps but where order is still implicit in the serialization’s textual order (such as JSON) will preserve the order of requested fields textually.
For example, if the request was { name, age }, a GraphQL service responding in JSON should respond with { "name": "Mark", "age": 30 } and should not respond with { "age": 30, "name": "Mark" }.