Acastaway

Acastaway provides an unofficial API for Acast.

Why?

• No need to faff about with API keys
• Uses the XML Feed under the hood with caching
• Can control pagination (XML feeds can be huge)
• Adds some nice extras, like a slug generated by the title
• Smart cache invalidation that purges all query parameter variations

Endpoints

Fetch Show Information

Retrieve information about a specific show using its ID.

curl https://acastaway.deno.dev/:id

Parameters

• :id: The show ID from Acast.
• page (optional): The page number, defaults to 1.
• limit (optional): The number of episodes per page, defaults to 10.

Response

{
  "title": "Show Title",
  "items": [
    {
      "id": "episode_id",
      "title": "Episode Title",
      "slug": "episode-slug",
      "description": "Episode Description",
      "created": "YYYY-MM-DDTHH:MM:SSZ",
      "published": "YYYY-MM-DDTHH:MM:SSZ",
      "enclosures": [
        {
          "url": "audio_file_url",
          "length": 123456,
          "type": "audio/mpeg"
        }
      ],
      "itunes": {
        "duration": "HH:MM:SS",
        "image": "image_url",
        "summary": "episode_summary",
        "type": "full"
      }
    },
    ...
  ],
  "page": 1,
  "limit": 10,
  "total_items": 100,
  "_debug": {
    "timestamp": "2025-01-01T00:00:00.000Z",
    "cache_control": "max-age=3600",
    "feed_description": "Show description..."
  }
}

Fetch Specific Episode Information

Get detailed information about a specific episode using its ID or slug.

curl https://acastaway.deno.dev/:id/:id_or_slug

Parameters

• :id: The show ID from Acast.
• :id_or_slug: The episode ID or slug.

Response

{
  "id": "episode_id",
  "title": "Episode Title",
  "description": "Episode Description",
  "created": "YYYY-MM-DDTHH:MM:SSZ",
  "published": "YYYY-MM-DDTHH:MM:SSZ",
  "enclosures": [
    {
      "url": "audio_file_url",
      "length": 123456,
      "type": "audio/mpeg"
    }
  ],
  "itunes": {
    "duration": "HH:MM:SS",
    "image": "image_url",
    "summary": "episode_summary",
    "type": "full"
  }
}

Cache Management

Webhook for Cache Refresh

Acastaway can automatically refresh the cache whenever you publish a new episode. To enable this feature:

1. Go to the Promotional Tools tab on your show in Acast.

2. Enable the Webhook switch.

3. Provide the following server endpoint address:

   https://acastaway.deno.dev

The webhook will automatically extract your show ID from the episode's audio URL and refresh the cache accordingly.

Now, whenever you publish a new episode, Acast will trigger a webhook that refreshes the cache for your show in Acastaway.

Manual Cache Invalidation

Manually making a POST request to this URL also invalidates the cache:

curl -X POST https://acastaway.deno.dev/:id

Cache Strategy

• Cache Duration: 1 hour (3600 seconds)
• Smart Invalidation: When cache is invalidated, ALL query parameter variations are purged
• Global Versioning: Uses cache versioning to ensure complete invalidation across all endpoints

Debug Endpoint

Check cache status for a specific show:

curl https://acastaway.deno.dev/debug/:id

Development

Prerequisites

• Deno (latest version)

Running Locally

# Install dependencies
deno cache main.ts

# Start the server
deno run --allow-net --allow-env --allow-read main.ts

Testing

# Run the test suite
deno task test

The test suite includes comprehensive coverage for:

• Basic endpoint functionality
• Pagination with different limits
• Cache behavior verification
• Cache invalidation testing
• Mock Acast API integration

Project Structure

• main.ts - Main application with Hono framework
• acast.ts - Acast API client with RSS parsing
• test.ts - Test suite with mocked dependencies
• deno.json - Deno configuration and tasks