GraphQL (OrchardCore.GraphQL)

GraphQL

The GraphQL module allows client applications to query the content handled by an Orchard websites. It enables the GraphiQL Explorer view to test GraphQL queries, and provides HTTP endpoints to send client queries.

HTTP Methods, Headers, and Body

GET request

When receiving an HTTP GET request, the GraphQL query should be specified in the "query" query string. For example, if we wanted to execute the following GraphQL query:

{
  me {
    name
  }
}

This request could be sent via an HTTP GET like so:

http://myapi/graphql?query={me{name}}

Query variables can be sent as a JSON-encoded string in an additional query parameter called variables. If the query contains several named operations, an operationName query parameter can be used to control which one should be executed.

POST request

application/json content type

A standard GraphQL POST request should use the application/json content-type header, and include a JSON-encoded body of the following form:

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

operationName and variables are optional fields. operationName is only required if multiple operations are present in the query.

application/graphql content type

Another option is to use the application/graphql content-type header, and the HTTP POST body contents is treated as the GraphQL query string.

query string

In addition to the above, If the "query" query string parameter is present (as in the GET example above), it will be parsed and handled in the same way as the HTTP GET case.

Response

Regardless of the method by which the query and variables were sent, the response is returned in the body of the request in JSON format. A query might result in some data and some errors, and those are returned in a JSON object of the form:

{
  "data": { ... },
  "errors": [ ... ]
}

If there were no errors returned, the "errors" field is not present on the response. If no data is returned the "data" field is only included if the error occurred during execution.

Authentication

Executing a GraphQL query requires the issuer to have the ExecuteGraphQL permission. Like any other API in Orchard Core, the GraphQL API supports cookie and OAuth 2.0 authentication. This means it's compatible with the OpenId module and supports JSON Web Token (JWT).

By default anonymous users are not able to execute a GraphQL query.