Medium GraphQL API

This API endpoint provides a proxy to fetch Medium post data using Medium’s GraphQL API with built-in caching.

Endpoints

GET /api/medium/post

Fetch a Medium post by its ID using query parameters.

Query Parameters:

• postId (required): The Medium post ID
• cookies (optional): Medium cookies for authenticated requests
• skipCache (optional): Set to true to bypass cache and fetch fresh data (default: false)

Examples:

# Standard request (uses cache)
curl "http://localhost:4321/api/medium/post?postId=YOUR_POST_ID"

# Bypass cache
curl "http://localhost:4321/api/medium/post?postId=YOUR_POST_ID&skipCache=true"

# With authentication
curl "http://localhost:4321/api/medium/post?postId=YOUR_POST_ID&cookies=YOUR_COOKIES"

POST /api/medium/post

Fetch a Medium post by its ID using JSON body.

Request Body:

{
  "postId": "YOUR_POST_ID",
  "cookies": "optional_cookies_string",
  "skipCache": false
}

Examples:

# Standard request (uses cache)
curl -X POST http://localhost:4321/api/medium/post \
  -H "Content-Type: application/json" \
  -d '{"postId":"YOUR_POST_ID"}'

# Bypass cache
curl -X POST http://localhost:4321/api/medium/post \
  -H "Content-Type: application/json" \
  -d '{"postId":"YOUR_POST_ID","skipCache":true}'

Response Format

Success Response (200)

{
  "data": {
    "post": {
      "id": "...",
      "title": "...",
      "content": {...},
      ...
    },
    "meterPost": {...}
  }
}

Error Responses

400 Bad Request - Missing postId:

{
  "error": "Missing required parameter: postId",
  "usage": "GET /api/medium/post?postId=YOUR_POST_ID"
}

500 Internal Server Error - Failed to fetch:

{
  "error": "Failed to fetch post",
  "postId": "..."
}

500 Internal Server Error - Exception:

{
  "error": "Internal server error",
  "message": "error details"
}

Caching

This API implements server-side caching using node-cache to improve performance and reduce load on Medium’s API.

Cache Configuration

• TTL (Time To Live): 1 hour (3600 seconds)
• Check Period: 120 seconds (automatically cleans up expired entries)
• Cache Key Format:
  • Without auth: post:{postId}
  • With auth: post:{postId}:auth

Cache Behavior

1. Cache Hit: Data is returned from cache (faster response, logs “Cache HIT”)
2. Cache Miss: Data is fetched from Medium API and cached (logs “Cache MISS”)
3. Cache Bypass: Use skipCache=true to force fresh data fetch

Response Headers

• Cache-Control: public, max-age=3600 - Instructs browsers to cache for 1 hour
• X-Cache-Status: HIT|BYPASS - Indicates whether cache was used

Benefits

• Faster response times for frequently accessed posts
• Reduced API calls to Medium’s servers
• Better performance under load
• Automatic cleanup of expired entries

Implementation Details

This API route is a TypeScript/Astro implementation that replicates the functionality of the Python MediumApiService from the freedium-library. It:

1. Caches responses for 1 hour to improve performance
2. Generates random SHA-256 operation IDs for each request
3. Uses the same GraphQL query as the Medium mobile app
4. Includes appropriate headers to mimic the Medium mobile client
5. Supports optional cookie authentication
6. Returns the full post data including content, metadata, and metering information

Request Headers

The API uses these headers to mimic the Medium mobile app:

• X-APOLLO-OPERATION-ID: Random SHA-256 hash
• X-APOLLO-OPERATION-NAME: “FullPostQuery”
• X-Client-Date: Current timestamp in milliseconds
• User-Agent: “AdsBot-Google-Mobile”
• Additional headers for GraphQL and content negotiation

Response Headers

• Content-Type: application/json
• Cache-Control: public, max-age=3600
• X-Cache-Status: HIT|BYPASS

How to Find a Medium Post ID

Medium post IDs can be extracted from the Medium URL or from the post’s source code. The post ID is typically a hash string that looks like abc123def456.

Example Medium URL:

https://medium.com/@username/article-title-abc123def456

The post ID would be: abc123def456