PRD Example 3: Weather Dashboard API

Difficulty: Advanced | Project Type: Shipped Product | Time: 2-3 weeks

---

Weather Dashboard API

Overview

What	A REST API that aggregates weather data and serves it to a simple dashboard
Who	Developers building weather-aware applications
Why	Provide a clean, cached interface to weather data with usage analytics

Features

1. Current Weather: GET /weather/\{city\} → Returns temperature, conditions, humidity
2. Caching: Responses cached for 10 minutes to reduce API calls
3. Usage Stats: GET /stats → Returns request counts per endpoint (last 24h)
4. Health Check: GET /health → Returns API status and upstream provider status
5. Simple Dashboard: Static HTML page showing weather for 3 preset cities

Non-Goals

Will NOT build:

• User accounts or authentication
• Weather forecasts (current conditions only)
• Historical weather data
• Mobile app or native clients
• Custom city lists per user
• Push notifications or alerts
• Rate limiting (MVP only)

Will NOT use:

• Frontend frameworks (React, Vue, etc.)
• ORMs (use raw SQL or simple key-value)
• Kubernetes or complex orchestration
• Multiple weather API providers

Technical Constraints

Language	Python 3.11+
Framework	FastAPI
Dependencies	httpx, redis, pytest, uvicorn
Database	Redis (caching + stats)
External API	OpenWeatherMap (free tier)
Testing	pytest, 80% coverage, mocked external calls
Deployment	Railway or Render (free tier)

API Response Format:

{
  "city": "London",
  "temperature": 15,
  "unit": "celsius",
  "conditions": "cloudy",
  "humidity": 72,
  "cached": true,
  "timestamp": "2025-01-15T10:30:00Z"
}

Error Response:

{
  "error": "City not found",
  "code": "CITY_NOT_FOUND"
}

Phases

Phase 1: Core API

Tasks: Set up FastAPI project, implement /weather/\{city\} endpoint with OpenWeatherMap. Verify:

uvicorn main:app --reload
curl http://localhost:8000/weather/london
# Returns JSON with temperature and conditions

Phase 2: Caching

Tasks: Add Redis caching. Cache responses for 10 minutes. Add cached: true/false to response. Verify:

curl http://localhost:8000/weather/london  # cached: false
curl http://localhost:8000/weather/london  # cached: true (instant)

Phase 3: Stats & Health

Tasks: Track request counts in Redis. Implement /stats and /health endpoints. Verify:

curl http://localhost:8000/stats
# Returns: {"weather_requests": 42, "period": "24h"}
curl http://localhost:8000/health
# Returns: {"status": "ok", "redis": "connected", "upstream": "ok"}

Phase 4: Dashboard & Deploy

Tasks: Create static/index.html with weather for London, NYC, Tokyo. Deploy to Railway. Verify: Visit deployed URL, see weather cards for 3 cities.

Agent Rules

Always	Ask First	Never
Handle API errors gracefully	Before adding new endpoints	Expose API keys in code
Return consistent JSON structure	Before changing response schema	Skip Redis connection handling
Log errors with context	Before adding new dependencies	Deploy without testing locally
Mock external APIs in tests	Before changing cache duration	Store sensitive data in Redis

Environment Variables

OPENWEATHER_API_KEY=xxx  # Required
REDIS_URL=redis://localhost:6379  # Default for local
PORT=8000  # Default