RSS feeds that don't break: caching, enclosures, and download analytics

Podcast distribution still depends on a small contract: a public RSS document, an <enclosure> URL, and an audio file that responds when apps fetch it. If the feed is slow, stale, or points at a broken tracker, a perfectly good episode can look unavailable.

ApexStream keeps the feed path deliberately plain. Render the published catalog, cache it, point the enclosure at the master MP3, and only add tracking when the redirect path has been verified.

What the public feed contains

Published shows are available from GET /v1/podcast/feed/:tenantId/:showSlug as application/rss+xml. The document uses RSS 2.0 with iTunes tags and Podcast Namespace fields such as GUIDs, transcripts, and chapters when those are present.

Unpublished episodes do not appear. Each published item includes an audio/mpeg enclosure and the byte length when it is known. The enclosure points to the finished master MP3 from the mastering step, not to an EDL source or a raw Studio asset.

Why the feed is cached for 15 minutes

Every feed render reads show metadata, published episodes, and asset URLs. Directories and podcast apps can request the same XML frequently, so the rendered document is stored in Redis for 900 seconds under a tenant-and-slug key. The implementation reads and writes that key without scanning all Redis keys.

The response also gives downstream caches a shorter, roughly five-minute Cache-Control window. Redis controls the origin's rebuild cost; the HTTP header is guidance for browsers, CDNs, and directories.

Publishing, unpublishing, editing metadata, and deleting an episode invalidate the feed key. The origin stops serving the old composition after the write path clears it, although a third-party directory can keep its own cached copy until that directory's timer expires.

Direct enclosures are the safe default

By default, the enclosure points directly to the CDN object for the master. Podcast apps fetch the audio from object storage rather than sending every download through the API. That keeps delivery independent from the feed-rendering service.

The tradeoff is measurement: a directory download that goes straight to the CDN never passes through ApexStream's product counter. Spotify, Apple, and Overcast requests are not automatically ApexStream download events just because they appear in a podcast app.

This is also why a sudden difference between a directory's number and the ApexStream number is not automatically a broken feed. They may be counting different events: a directory can measure plays or requests in its own system, while ApexStream only measures a request that passed through its optional redirect.

When enclosure tracking is enabled

An operator can enable an opt-in tracking path where the enclosure points to an API /track/... URL. The handler records the request and redirects it to the same CDN file.

Tracking requires both PODCAST_ENCLOSURE_TRACKING=true and a non-empty, operator-verified PODCAST_TRACKING_BASE. A bad base URL would turn every enclosure into a 404, so enablement is deliberately manual. Before switching it on, request a published track URL and confirm that it returns a redirect to the master MP3. If the flag is unset, enclosures fall back to CDN-direct delivery.

What the number means

With tracking enabled, a counted download is a request that reached the redirect. With tracking disabled, the dashboard should not imply that CDN edge requests are metrics ApexStream owns. Spotify can report its own consumption inside Spotify, and that number will not necessarily match an origin counter.

Feed requests can still record user-agent information to help distinguish crawlers from other readers. The feed remains public; RSS is not an authenticated API.

If an app has not refreshed after a publish or metadata change, remember the two clocks: ApexStream invalidates its origin key immediately, while the app may hold its own cached copy. That delay is normal for a public feed and does not require changing the enclosure URL.

The boring rules that keep RSS healthy

• Cache the XML and invalidate it whenever published content changes.
• Do not make analytics a prerequisite for audio delivery.
• Use CDN-direct enclosures unless the tracking redirect has been tested.
• Describe third-party directory numbers as third-party numbers.

A feed should work when a directory checks it at 3 a.m. Caching, correct enclosures, and a verified optional tracker are enough.

The point is not to turn RSS into a metrics system. The point is to publish a stable document that keeps pointing listeners to the master file.

Frequently asked questions

Why does an updated episode take time to appear?

Podcast apps and directories cache feeds and audio enclosures. Confirm that the episode is published and the feed contains the new item before assuming the directory is broken.

Does RSS show exact listener numbers?

RSS delivery data is useful for distribution context, but it is not a perfect cross-platform audience measurement. Use the available analytics as a directional signal.