Purge pages when the origin publishes a change

You make a publishing system, such as a CMS, a commerce platform, or a build pipeline, purge the pages it changes through the Azion API or the Azion CLI, and send the same purge by hand from Azion Console. For a one-off purge of any type, refer to Purge cached content.

A published change reaches visitors only after the cached copy leaves the cache. The publishing system knows which pages changed, so it sends the purge the moment it saves them, and the cache TTL stays a safety bound for a purge that is missed.

mermaid

%%{init: {"layout": "dagre", "themeVariables": {"fontSize": "13px"}, "flowchart": {"nodeSpacing": 12, "rankSpacing": 12, "padding": 6, "wrappingWidth": 70, "minNodeWidth": 40, "useMaxWidth": true}}}%%

02flowchart TD

03 Save["The origin saves a change"] --> Url["URL purge: the page and the pages that list it"]

04 Save --> Images{"Did the images change?"}

05 Images -->|"yes"| Wild["Wildcard purge: every size and format of the images"]

06 Images -->|"no"| Skip["No image purge"]

07 Url --> History["The purge appears in the purge history"]

08 Wild --> History

09 History --> Miss["The next request carries x-cache: MISS"]

On every save, the publishing system sends a URL purge for the changed page and the pages that list it.
Only when the save changes images, it also sends a wildcard purge for every size and format of those images.
Each purge appears in the purge history when it is complete, and the next request for each object reaches the origin.

Prerequisites

Console

A domain that belongs to your account, served by an application. A purge of any other domain is rejected with error 30003.
Access to Azion Console. Refer to Access Azion Console.

CLI

A domain that belongs to your account, served by an application. A purge of any other domain is rejected with error 30003.
A personal token. A token expires 1 day after it is created unless you choose a longer expiration, so set one that covers the time the publishing system runs, and replace the token before it expires.
The Azion CLI installed and authorized.

API

A domain that belongs to your account, served by an application. A purge of any other domain is rejected with error 30003.
A personal token. A token expires 1 day after it is created unless you choose a longer expiration, so set one that covers the time the publishing system runs, and replace the token before it expires.

The examples purge the product page https://www.example.com/products/blue-shirt, its category page https://www.example.com/category/shirts, and the images under www.example.com/media/blue-shirt. Replace them with the objects your save changes.

Purge the changed pages on every save

A URL purge removes the exact URLs it lists. It is not recursive, so list each page the change affects: the page itself and every page that shows the changed content, such as a category page or a home page. One request carries up to 50 URLs. A URL without a scheme purges both the HTTP and the HTTPS copies.

Console

To send the URL purge by hand:

Open Real-Time Purge

Access Azion Console > Products Menu > Real-Time Purge.

Select New Purge

Choose the URL purge type and the Cache layer

Enter the URLs

Enter one URL per item: https://www.example.com/products/blue-shirt and https://www.example.com/category/shirts.

Select Purge

A message confirms the creation, and Azion queues the purge.

CLI

To send the URL purge from a script, pass the URLs as one comma-separated list:

azion purge --urls "https://www.example.com/products/blue-shirt,https://www.example.com/category/shirts"

The command prints one line:

Purge carried out successfully

API

To send the URL purge from the publishing system, call the url purge path with the token:

Shell

01curl --request POST \

02 --url https://api.azion.com/v4/workspace/purge/url \

03 --header 'Authorization: Token <personal-token>' \

04 --header 'Content-Type: application/json' \

  --data '{"items":["https://www.example.com/products/blue-shirt","https://www.example.com/category/shirts"],"layer":"cache"}'

The API answers with HTTP 201 and state set to executed:

{"state":"executed","data":{"items":["https://www.example.com/products/blue-shirt","https://www.example.com/category/shirts"],"layer":"cache"}}

The listed pages leave the cache once the purge propagates. A URL purge does not reach the copies that vary by cookie, device group, or image format, which the next section covers for images.

The Build e-commerce storefronts use case uses the values of this example.

Purge image variants when an image changes

Image Processor caches one copy of an image per size and per format, and a URL purge reaches none of those copies. A wildcard purge ending in * reaches all of them. Send it only when the save changes an image: Azion accepts 2,000 wildcard purge requests in a 24-hour interval, and a wildcard on every save of a large catalog can reach that bound. One request carries one expression of up to 256 characters.

Console

To send the wildcard purge by hand:

Open Real-Time Purge

Access Azion Console > Products Menu > Real-Time Purge.

Select New Purge

Choose the wildcard purge type and the Cache layer

Enter the expression

Enter www.example.com/media/blue-shirt*.

Select Purge

A message confirms the creation, and Azion queues the purge.

CLI

To send the wildcard purge from a script:

azion purge --wildcard "www.example.com/media/blue-shirt*"

The command prints one line:

Purge carried out successfully

API

To send the wildcard purge, call the wildcard purge path with one expression:

Shell

01curl --request POST \

02 --url https://api.azion.com/v4/workspace/purge/wildcard \

03 --header 'Authorization: Token <personal-token>' \

04 --header 'Content-Type: application/json' \

05 --data '{"items":["www.example.com/media/blue-shirt*"]}'

The API answers with HTTP 201, and without layer it purges cache:

{"state":"executed","data":{"items":["www.example.com/media/blue-shirt*"],"layer":"cache"}}

Every size and format of the changed images leaves the cache. When the publishing system knows the exact variants it serves, a cache key purge that lists each key does the same work without counting against the wildcard bound. A key carries the processing arguments after ? and the format after @@, as in httpswww.example.com/media/blue-shirt.jpg?ims=400x@@webp. For the format, refer to Cache keys.

URL and wildcard purges clear the Cache layer only. On an application whose cache setting has Tiered Cache on, purge the Tiered Cache layer first with a cache key purge, then the Cache layer, so the cache is not refilled from a stale copy. For the steps, refer to Purge cached content.

In the Build and run marketing websites use case, this section takes these values:

Purge	When	Items
Wildcard, on the Cache layer	Once per push, after its deploy completes	`www.example.com/*`, every page of the domain

Every page of www.example.com leaves the cache once the purge propagates, and the next request for each one reads the new build. To confirm a purge completed, find it in the purge history, as Confirm the purge completed describes.

The Build e-commerce storefronts use case uses the values of this example.

Confirm the purge completed

A 201 from the API means the purge was accepted, not that it has propagated. Azion lists a purge in the purge history when it is complete. To confirm it:

Open Real-Time Purge

Access Azion Console > Products Menu > Real-Time Purge.

Find the purge in the history

The history lists each completed purge, and it can be filtered by the user who made it, the time, the argument list, the purge type, and the method. Filter by the argument list to find the URL or the expression you sent.

Request the page with the debug header

curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/products/blue-shirt

Read the cache status

The response carries MISS, because Azion fetched the page from the origin again:

x-cache: MISS from 192.0.2.10 with HTTP/2.0

The purge is in the history, and the page served after it is the version the origin published. The request after it carries HIT again.

A publishing system that saves many objects at once, such as a catalog import, sends URLs in batches of 50 or fewer. Azion accepts 10,000 URL and cache key objects every 60 seconds. For every purge bound, refer to Real-Time Purge limits.

In the Build and run marketing websites use case, expect:

A push reaches the page. Change the text of the /about/ page, commit, and push. Wait for the deploy to complete, send the wildcard purge, and request the page again. The response carries x-cache: MISS and the new text, and the request after it carries HIT.

These checks confirm the Build e-commerce storefronts use case.

Next steps

Purge cached contentPurge by cache key, purge the Tiered Cache layer, and purge objects that vary.Real-Time PurgeEvery purge type, the variations each one reaches, the errors, and the limits.Build e-commerce storefrontsA storefront that purges product pages from the commerce platform on every save.Azion CLI purgeEvery flag of the azion purge command.Build and run marketing websitesA marketing site deployed from GitHub on every push and purged by wildcard after each deploy.