Cache and ETag
The per-site route is kept at the Cloudflare edge and purged when the post changes; every response has an ETag.
Every 200 or 301 response carries a strong ETag. Send it in If-None-Match and the API answers 304 Not Modified, with no body, when nothing changed:
curl -i -H "Authorization: Bearer $POSTREAM_API_KEY" \
-H 'If-None-Match: "3f1c…"' \
"https://api.postream.blog/public/v1/sites/$POSTREAM_SITE_ID/posts/managing-many-blogs"Per-site route: edge cache
On the /public/v1/sites/{siteId}/… route the content is what is already published, the same for every key, so Cloudflare keeps the response:
| Response | Cache-Control |
|---|---|
Post (and the 301 of an old slug) | public, max-age=60, s-maxage=86400, stale-while-revalidate=604800, stale-if-error=86400 |
Lists, authors, pillars, site and sitemap | public, max-age=60, s-maxage=300, stale-while-revalidate=604800, stale-if-error=86400 |
Error (4xx, 5xx) | no-store |
Vary: Accept-Encodingonly. That is why this route has no CORS and noRateLimit-*headers (onlyRetry-Afteron the429).- The key is only checked when the request reaches Postream (a cache miss). A cached copy is served to anyone who asks for the same URL: the content is what is already live on the blog.
Purge when the post changes
When a post is published, unpublished, edited after publication or deleted, Postream asks Cloudflare to purge the affected URLs: the post with and without ?locale=, in every language, the first page of the lists it appears in (all, by language, by tag, by language and tag) and the sitemap. The purge runs in the background, with retries, and never delays publication.
The purge is by exact URL, query string included. To benefit from it, call the URLs in the canonical form:
?locale=before&tag=;- values with
encodeURIComponent; - no
page=1.
Other pages, another perPage, authors, pillars and site keep the 5 minutes at the edge. The SEO kit already builds the URLs this way.
Key route
On /public/v1/posts… the same address answers for different sites depending on the key, so the response comes with Cache-Control: private, no-cache and Vary: Origin, Authorization: only the blog and the browser store it, always revalidating with the ETag. no-cache does not forbid storing: it says the copy must be revalidated before each use.
On the blog's side
There are three layers, each with its own timing:
- Cloudflare edge (Postream): purged by Postream itself when the post changes.
- Next.js cache on the blog:
next: { revalidate: 300 }fetches again at most every 5 minutes; since the edge has already been purged, the next fetch brings the new post. - Visitor's browser:
max-age=60only applies to calls made straight from the browser.
await fetch(`${process.env.POSTREAM_API_URL}/sites/${process.env.POSTREAM_SITE_ID}/posts?locale=en-US`, {
headers: { Authorization: `Bearer ${process.env.POSTREAM_API_KEY}` },
next: { revalidate: 300, tags: ["postream"] },
});For a post to show up on the blog right after it is published, without waiting for the interval, use webhooks: they call the blog right away, and the blog runs revalidatePath or revalidateTag.