Why does GraphQL query work with the "query" keyword before the curly braces? - asp.net-core

Question

I created a small API for authors and books as example. The problem is that I don't understand why a query can look different but still get me the same output. I've included 3 examples.
The GraphQL query looks like this:
{
"query":
"query{
author(id: 1) {
name
}
}"
}
Why is this query working if within the query is the keyword "query" two times? When I write the query like this:
{
"query":
"{
author(id: 1) {
name
}
}"
}
it also works, and when I write it like that:
{
"query":
"author{
author(id: 1) {
name
}
}"
}
It is not working. Why is that so?

Answer 1

GraphQL specifies three types of operations:
query – a read‐only fetch.
mutation – a write followed by a fetch.
subscription – a long‐lived request that fetches data in response to source events.
What you are sending to your server is a JSON object with a single property (query) the value of which is a GraphQL document that represents your actual request to the GraphQL service. This property is (unfortunately) called query by convention but it has nothing to do with the actual operation inside the document you are sending.
Any operation included in your GraphQL document must follow this format:
OperationType [Name] [VariableDefinitions] [Directives] SelectionSet
Name, VariableDefinitions and Directives are all optional. The OperationType is one of query, mutation or subscription. SelectionSet is the collection of fields you are requesting for that operation type. Only selection sets are wrapped in curly brackets. In your example, you have two selection sets -- one containing the author field and one containing the name field.
There's an exception to the above called query shorthand:
If a document contains only one query operation, and that query defines no variables and contains no directives, that operation may be represented in a short‐hand form which omits the query keyword and query name.
In other words if your operation:
is a query
is the only operation in the document
contains no variable definitions or directives
You can omit the query keyword and the operation name. This leaves you with just a selection set, which is wrapped in a set of curly brackets.
So your first two examples are equally valid. The third example is not valid because author is not a valid operation kind.

Answer 2

The first query key on your examples is a requirement from GraphQL to actually call the endpoint, it has to be present to actually run queries or mutations. You can see it in the docs.
The first example works because at the root of a GraphQL Schema there has to be an action with keywords query or mutation, and in your case you are triggering a query.
The second example works because if you don't define what type of action (query or mutation) on your request, it always defaults to execute a query.
The third example does not work because you don't have the action author at the root of your Schema.
I guess the first keyword query is what makes some confusion in this case.