Gofi API Documentation

Gofi is a high-performance RSS/Atom-to-JSON proxy service. Use the endpoints below to issue tokens and fetch normalized feed data.

Authentication

All API requests require a valid Bearer token in the Authorization header.
Obtain a token via the POST /v1/tokens endpoint (admin only).

Authorization: Bearer <your-token>
        

Endpoints

1. POST /v1/tokens (Admin only)

Issue a new API token. Requires X-Admin-Token header.

Request:

POST /v1/tokens
X-Admin-Token: <admin-secret>
        

Response (201 Created):

{
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
        

2. GET /v1/feed

Fetch and normalize an RSS/Atom feed as JSON.
Requires Bearer token and is rate-limited per token.

Query Parameters:

Name	Type	Description
rss_url	string	Required. The feed URL to fetch.
count	integer	Optional. Max number of items to return.

Request Example:

GET /v1/feed?rss_url=https://blog.golang.org/feed.atom&count=5
Authorization: Bearer <your-token>
        

Response Example:

{
  "status": "ok",
  "feed": {
    "title": "Example Blog",
    "link": "https://example.com",
    "description": "An example feed",
    "image": "https://example.com/logo.png",
    "updated": "2025-05-13T10:00:00Z"
  },
  "items": [
    {
      "title": "Post title",
      "link": "https://example.com/post",
      "author": "Author Name",
      "pubDate": "2025-05-12T08:30:00Z",
      "content": "...",
      "description": "...",
      "categories": ["tag1","tag2"],
      "enclosure": {
        "url": "...", "type": "audio/mpeg", "length": "12345"
      }
    }
    // ...
  ]
}
        

Errors

• 401 Unauthorized — Missing or invalid token
• 403 Forbidden — Invalid admin secret (for token issuance)
• 429 Too Many Requests — Rate limit exceeded
• 400 Bad Request — Missing or invalid parameters
• 502 Bad Gateway — Feed fetch/parse error

Environment Variables

Variable	Default	Description
REDIS_ADDR	localhost:6379	Redis server address
REDIS_PASSWORD	(empty)	Redis password
REDIS_DB	0	Redis DB index
RATE_LIMIT	1000-H	Requests per period (e.g. 100-H, 5000-D)
ADMIN_SECRET	(empty)	Secret for token issuance
PORT	8080	HTTP server port

Notes

• All endpoints are under /v1/.
• Feed responses are cached for 15 minutes.
• Rate limiting is enforced per token.