5. Caching client APQ
2m

Overview

When receiving queries from a client, the takes on the role of a traditional . To reduce the amount of data sent over the network, clients can use to send the router an hash in place of the entire operation string.

In this lesson, we will:

  • Walk through how the validates and processes from a client
  • Review configuration options for client

APQ from the client

We can mimic a client—such as a frontend app running Apollo Client, which supports —using a curl command in the terminal.

Let's build out our command. We'll send a new request to our on http://127.0.0.1:5000. Next, define a --header flag with a value of 'content-type: application/json'.

curl --get http://127.0.0.1:5000 \
  --header 'content-type: application/json'

We'll also specify two separate instances of --data-urlencode.

curl --get http://127.0.0.1:5000 \
  --header 'content-type: application/json' \
  --data-urlencode # TODO
  --data-urlencode # TODO

Recall that the first time we send the to the , we need to send the actual full-length query string AND its identifier (its SHA-256 hash).

Let's use the first --data-urlencode flag to pass in our entire string. We include it in the following format:

--data-urlencode 'query={featuredListings{description id title}}'

To include the hash as part of the second --data-urlencode flag, we'll define a lengthier string with some additional data. We start by specifying extensions, and set it equal to an object with a persistedQuery key. As the value for persistedQuery, we'll define another object.

--data-urlencode 'extensions={"persistedQuery":{}}'

This next object takes two keys: version and sha256hash. We've pre-calculated the SHA-256 hash of the provided , so you can copy the contents below.

--data-urlencode 'extensions={"persistedQuery":{"version":1,"sha256Hash":"91c070d387e026c84301ba5d7b500a5647e24de65e9dd9d28f4bebd96cb9c11c"}}'

Note: We derived the SHA-256 hash for the string by passing {featuredListings{description id title}} exactly (no extra spaces!) into a SHA-256 generator.

Here's what the entire command should look like. Pop open a terminal, and let's run it!

curl --get http://127.0.0.1:5000 \
  --header 'content-type: application/json' \
  --data-urlencode 'query={featuredListings{description id title}}' \
  --data-urlencode 'extensions={"persistedQuery":{"version":1,"sha256Hash":"91c070d387e026c84301ba5d7b500a5647e24de65e9dd9d28f4bebd96cb9c11c"}}'

After just a moment, we'll see the response with our data!

Now let's try it again; this time removing the full string from our curl command.

curl --get http://127.0.0.1:5000 \
  --header 'content-type: application/json' \
  --data-urlencode 'extensions={"persistedQuery":{"version":1,"sha256Hash":"91c070d387e026c84301ba5d7b500a5647e24de65e9dd9d28f4bebd96cb9c11c"}}'

With this command, we can send just the identifier, and our knows exactly which operation we're talking about. We should see the exact same response in the terminal as before.

Note: We're using a curl command here to quickly showcase how works in action. To work correctly, the client sending the queries needs logic to generate the identifiers for the APQ, make requests to the using the hashed queries, and if necessary, retry requests with the full string and the hash. To read more about configuring this behavior using , check out the Apollo documentation.

Caching client operation APQ

The enables caching client by default. We can further customize how many operations it stores, or even turn off the feature entirely, by setting some flags in our router-config.yml file.

Limits the number of APQ in the cache to 100
apq:
  router:
    cache:
      in_memory:
        limit: 100
Alternatively, disables client APQ support
apq:
  enabled: false

We can also cache our in a distributed cache, which we'll see later on in the course.

Practice

Automatic persisted queries and the router
Automatic persisted queries enable the router to send and receive a query's 
 
 rather than the entire 
 
. To cache an APQ, the router must first receive 
 
, which it then validates and stores for the future. Receiving APQ from a client 
 
, whereas sending APQ to subgraph servers 
 
.

Drag items from this box to the blanks above

  • both the query string and its corresponding hash

  • operation string

  • must be configured separately

  • is configured by default

  • SHA-256 hash

  • SHA-512 hash

  • the query plan

  • introspection response

  • is not supported

Key takeaways

  • To support sending the , a client should implement the logic to convert strings to hashes, to send the router these hashes, and to retry the request in the event the router requires the original string. supports APQ out of the box.

Up next

Receiving queries from clients isn't the 's only job; it must also divide queries between the responsible for providing data. In the next lesson, we'll walk through how the router takes on the role of client when sending to subgraphs.

Share your questions and comments about this lesson

This course is currently in

beta
. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.