Purging API

GraphCDN automatically creates a custom GraphQL API, the so-called Purging API, for your service that allows you to purge your cache. Purging the cache globally takes at most 150ms.

To try the purging API, head to the "Purging API" tab on your service's dashboard.

📘

In most cases, you don't need to manually purge because of the Automatic Cache Invalidation via Mutations supported by GraphCDN.

Programmatic usage

The purging API for your service is available at https://admin.graphcdn.io/<service-name>.

Authentication

To use your service's purging API you need to authenticate with a Purging API Token. To create a new one, go to your service's "Settings" tab and navigate to the "Purging API Tokens" section.

You might already see some tokens in the list called something like dashboard-74asd8 that you did not create. This is nothing to worry about. When you navigate to the "Purging API" tab on your service's dashboard we automatically create a new token so you can try it out without having to create one manually.

To send a request to the purging API you need to send the purging API token in the graphcdn-token header.

For example, here is how to access the API from Node.js.

const fetch = require('node-fetch') 

async function purgeAllPosts() {  
  await fetch('<https://admin.graphcdn.io/little-frog>', { 
    // Always use POST for purge mutations
    method: 'POST',
    headers: {
      // and specify the Content-Type
      'Content-Type': 'application/json',
      'graphcdn-token': 'das09dja09sjda0s9ja...',
    },
    body: JSON.stringify({ query: `mutation { purgePost }` }),
  })
}

purgeAllPosts().catch((e) => console.error(e))

If you want to try it in the GraphQL playground use the "HTTP Headers" tab at the bottom.

The purging API gives you access to fine-grained purging mutations that you can use to invalidate any data that has changed right from your backend.

📘

It is preferable to purge as fine-grained as possible. The less data you invalidate the higher your cache hit rate will be.

Purge all occurrences of a specific object

This is the most specific purge mutation that is available. Use this unless you have a reason not to!

You can purge all queries that contain a specific object/node, for example, the User with the ID 5:

mutation { purgeUser(id: [5]) }

Of course, since this is GraphQL, you can purge as many specific objects/nodes as you want at once:

mutation { purgeUser(id: [1, 2, 5, 7]) purgePost(id: [12, 13]) }

Purging by a field of the query root type

With this mutation you can purge all cached results for a field of the Query root type. For example, all results of queries that contain a list of posts (like { posts { ... } }) can be purged with:

mutation { _purgeQuery(queries: [posts]) }

📘

The name of the _purgeQuery mutation starts with an underscore, as we don't want this generic name to conflict with your specific types.

Purging by an operation name

With this mutation, you can purge all cached results of the query with the operation name(s) you provide. For example, to invalidate all results of queries named listUsers and listPosts:

mutation { _purgeOperationName(names: ["listUsers", "listPosts"]) }

📘

The name of the _purgeOperationName mutation starts with an underscore, as we don't want this generic name to conflict with your specific types.

Purging all occurrences of a GraphQL type

You can purge all query results that contain any instance of an object. For example, to purge all cached results of queries that have any user in them, simply purge all users by not passing the id argument:

mutation { purgeUser }

Purging everything

❗️

Purging all queries will temporarily increase traffic to your origin server while we don't have anything cached anymore. Use this sparingly as a last resort and make sure your origin servers can handle the resulting traffic spike.

You can purge all cached results GraphCDN has stored with the special _purgeAll mutation. Be extra careful when using this, as it will cause a traffic spike to your origin server.


Did this page help you?