PRD Example 17: RSS Feed Aggregator API

Difficulty: Intermediate | Project Type: REST API | Time: 6-8 hours

---

Overview

What	A REST API for aggregating and managing RSS feeds
Who	Developers building news readers or content aggregators
Why	Provides a unified API to fetch and cache RSS content from multiple sources

---

Core Features (MVP)

1. Add Feed: POST /feeds → Subscribe to RSS feed by URL
2. List Feeds: GET /feeds → Show all subscribed feeds
3. Get Articles: GET /feeds/\{id\}/articles → Get articles from a feed
4. Refresh Feed: POST /feeds/\{id\}/refresh → Fetch latest articles
5. Delete Feed: DELETE /feeds/\{id\} → Unsubscribe from feed

---

Non-Goals

Will NOT build:

• User accounts or authentication
• Read/unread article tracking
• Article favoriting or bookmarking
• Full article content fetching (only RSS summary)
• OPML import/export
• Push notifications
• Automatic background refresh
• Search across articles

Will NOT use:

• Database (use JSON file)
• Background job processors
• Caching services (Redis, etc.)
• Authentication libraries

---

Technical Constraints

Language	Node.js 20+
Framework	Express.js
Dependencies	express, rss-parser, uuid
Data Storage	JSON file at ./data/feeds.json
Testing	Jest, supertest
Code Style	ESLint, Prettier

---

Success Criteria

• [ ] POST /feeds validates RSS URL and stores feed info
• [ ] GET /feeds returns all feeds with article count
• [ ] GET /feeds/\{id\}/articles returns parsed articles
• [ ] POST /feeds/\{id\}/refresh fetches latest articles
• [ ] DELETE /feeds/\{id\} removes feed
• [ ] Handles invalid RSS URLs gracefully
• [ ] All tests pass

---

Implementation Phases

Phase 1: Project Setup & Feed Management

Goal: Set up Express and feed CRUD

Tasks:

1. Create Express project with TypeScript
2. Define Feed type: \{id, url, title, lastRefreshed\}
3. Implement POST /feeds with URL validation
4. Implement GET /feeds and DELETE /feeds/\{id\}

Verification:

npm run dev
# Server starts on http://localhost:3000

curl -X POST http://localhost:3000/feeds \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hnrss.org/frontpage"}'
# Returns: {"id": "abc123", "title": "Hacker News", ...}

curl http://localhost:3000/feeds
# Returns array of all feeds

Deliverables: Express server with feed endpoints

---

Phase 2: RSS Parsing & Articles

Goal: Fetch and parse RSS content

Tasks:

1. Use rss-parser to fetch feed content
2. Store articles in feed data
3. Implement GET /feeds/\{id\}/articles
4. Parse article: \{title, link, pubDate, summary\}

Verification:

curl http://localhost:3000/feeds/abc123/articles
# Returns:
# {
#   "feed": {"id": "abc123", "title": "Hacker News"},
#   "articles": [
#     {"title": "Show HN: ...", "link": "...", "pubDate": "..."},
#     ...
#   ]
# }

Deliverables: Article parsing and retrieval

---

Phase 3: Refresh & Testing

Goal: Manual refresh and tests

Tasks:

1. Implement POST /feeds/\{id\}/refresh
2. Update lastRefreshed timestamp
3. Handle RSS parsing errors gracefully
4. Write Jest tests with mocked RSS responses

Verification:

curl -X POST http://localhost:3000/feeds/abc123/refresh
# Returns: {"message": "Refreshed", "newArticles": 5}

# Test invalid URL
curl -X POST http://localhost:3000/feeds \
  -d '{"url": "not-a-valid-rss"}'
# Returns: {"error": "Invalid RSS feed URL"}

npm test
# All tests pass

Deliverables: Complete API with tests

---

Data Schema

interface Feed {
  id: string;
  url: string;
  title: string;
  description?: string;
  lastRefreshed: string; // ISO date
  articles: Article[];
}

interface Article {
  title: string;
  link: string;
  pubDate: string;
  summary?: string;
  guid: string;
}

---

Agent Rules

Always	Ask First	Never
Validate URL is valid RSS before storing	Before adding new endpoints	Use database
Handle RSS parsing errors gracefully	Before changing article schema	Store full article content
Return proper HTTP status codes	Before adding authentication	Auto-refresh in background
Limit articles per feed (max 50)		Scrape website content