Operation Request Format
Send requests to the Apollo Router over HTTP
By default, almost every GraphQL IDE and client library takes care of sending operations in a format that the Apollo Router supports. This article describes that format, which is also described on graphql.org and in this preliminary spec.
The Apollo Router accepts queries, mutations, and subscriptions sent as POST requests. It also accepts queries sent as GET requests.
POST requests
The Apollo Router accepts POST requests with a JSON body. A valid request contains a query
field, along with optional variables
and an operationName
(if query
contains multiple possible operations).
Let's say we want to execute the following query:
1query GetBestSellers($category: ProductCategory) {
2 bestSellers(category: $category) {
3 title
4 }
5}
Here's an example of a valid POST request body for that query:
1{
2 "query":"query GetBestSellers($category: ProductCategory){bestSellers(category: $category){title}}",
3 "operationName": "GetBestSellers",
4 "variables": { "category": "BOOKS" }
5}
Note that operationName
isn't required for this particular request body, because query
includes only one operation definition.
You can execute this query against an Apollo-hosted example server right now with the following curl
command:
1curl --request POST \
2 -H 'Content-Type: application/json' \
3 --data '{"query":"query GetBestSellers($category:ProductCategory){bestSellers(category: $category){title}}", "operationName":"GetBestSellers", "variables":{"category":"BOOKS"}}' \
4 https://rover.apollo.dev/quickstart/products/graphql
The Apollo Router's default landing page provides a curl
command you can use to execute a test query on your own server:
1curl --request POST \
2 --header 'content-type: application/json' \
3 --url 'http://127.0.0.1:4000/' \
4 --data '{"query":"query { __typename }"}'
GET requests
The Apollo Router also accepts GET requests for queries (but not mutations). With a GET request, query details (query
, operationName
, variables
) are provided as URL query parameters. The variables
option is a URL-escaped JSON object.
Here's the same query from POST requests formatted for a curl
GET request:
1curl --request GET \
2 https://rover.apollo.dev/quickstart/products/graphql?query=query%20GetBestSellers%28%24category%3AProductCategory%29%7BbestSellers%28category%3A%20%24category%29%7Btitle%7D%7D&operationName=GetBestSellers&variables=%7B%22category%22%3A%22BOOKS%22%7D
Persisted queries protocol
The Automatic Persisted Queries (APQ) and Persisted Query List (PQL) features of the Apollo Router use a separate protocol to send the operation document information in the extensions
. This protocol can also use HTTP POST or GET. See the Apollo Client docs on the APQ protocol for details.
Related topics
From the Apollo blog: Making GraphQL Requests using HTTP Methods