Another critical concept to understand when working with the Stellate Edge Cache is Scopes. Think of scopes as a way to split your cache into various buckets for different users or queries. Each bucket is secured by a specific key that needs to be present on a request for a particular cached document to be served from that bucket.

Each service has a unique scope called PUBLIC that is available without any keys. So if your service only serves publicly available information, that's all you need.

You can define custom scopes based on HTTP headers, cookies, or a combination of those. For example, a common use case for scopes is creating a scope for authenticated users based on the Authorization header or a session cookie.

For example, let's say we have a scoped configured called AUTHENTICATED, which is based on a header called Authorization. We're also going to use our SpaceX API for the following examples, which is configured to cache the query we're using with that specific scope. (How to configure your cache to cache specific types with specific scopes is part of the next chapter.)

We're going to send the following query multiple times, and we're going to use different values for the Authorization header.

{ 
    roadster {
        name
        earth_distance_km
    }
}

To make it easier to send multiple requests, we've saved the commands to a shell script called test-scopes.sh in our current directory. That script also allows us to pass in the value for the Authorization header via an environment variable.

#!/bin/sh
curl -g -D - -X POST https://spacex-api.stellate.sh \
  -H "Content-Type: application/json" \
  -H "Authorization: ${AUTHORIZATION}" \
  -d '{ "query": "{ roadster { name earth_distance_km } }" }'

Amanda, our first user, sees a cache miss the first time she runs that query. This is indicated by the MISS in the gcdn-cache response header. However, if she sends the same query again, she will see a cache HIT instead.

# First request, produces a cache miss and adds the document to the cache for Amanda
$ AUTHORIZATION="amanda" ./test-scopes.sh
HTTP/2 200 
#... (some headers removed for brevity)
gcdn-cache: MISS
{"data":{"roadster":{"name":"Elon Musk's Tesla Roadster","earth_distance_km":57928338.62299857}}}

# Second request, a cache hit, because Amanda already requested that document and it is stored in her cache
$ AUTHORIZATION="amanda" ./test-scopes.sh
HTTP/2 200 
#... (some headers removed for brevity)
gcdn-cache: HIT
{"data":{"roadster":{"name":"Elon Musk's Tesla Roadster","earth_distance_km":57928338.62299857}}}

Mike, a different user, wants to know more about that Roadster. So he sends the same GraphQL query. However, he uses mike as the value for the AUTHORIZATION header.

# Mike didn't request that document yet, and doesn't have access to Amandas cache, so he gets a cach miss initially
$ AUTHORIZATION="mike" ./test-scopes.sh
HTTP/2 200 
#... (some headers removed for brevity)
gcdn-cache: MISS
{"data":{"roadster":{"name":"Elon Musk's Tesla Roadster","earth_distance_km":57928338.62299857}}}

Because Mike didn't send that query previously and doesn't have access to Amanda's cache, he will see a cache miss on his first request. However, if he sends the same query again, he would get a cache hit, as Amanda did on her second request.

Scopes allow you to cache documents that are different for different users and improve your application's performance even in use cases where data is not shared between users.


What’s Next
Did this page help you?