From 9745cdeaa644071562de59105d555b90a64e36bf Mon Sep 17 00:00:00 2001 From: Aherobo Ovie Victor Date: Tue, 8 Jul 2025 19:07:57 +0100 Subject: [PATCH] docs: Comprehensive update to API endpoints documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 📚 ENHANCED API DOCUMENTATION: - Detailed descriptions for all 13 API endpoints - Added parameters, request/response formats for each endpoint - Organized by functional categories (Core, News, Recommendations, Search, AI) - Added use cases and practical examples for each endpoint - Comprehensive parameter documentation with defaults ✅ COMPLETE ENDPOINT COVERAGE: - Core System (3): /, /health, /stats - News Management (2): /fetch-news, /articles - Recommendations (4): /recommend-news, /recommend-by-query, /recommend-by-interests, /trending - Search & Discovery (1): /search - AI Analysis (3): /analyze-article, /generate-insights, /ai-status 🚀 Ready for developer onboarding and API integration! --- docs/README.md | 99 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 80 insertions(+), 19 deletions(-) diff --git a/docs/README.md b/docs/README.md index 4dc2b44..bdbd26e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -84,28 +84,89 @@ DS_Task_AI_News/ ## API Endpoints (13 Total) -### **Core System (3)** -- `GET /` - Root health check -- `GET /health` - Detailed system health & statistics -- `GET /stats` - System metrics and performance data +### **Core System Endpoints (3)** -### **News Management (2)** -- `POST /fetch-news` - Fetch fresh articles from RSS feeds -- `GET /articles` - Get articles with pagination & advanced filtering +#### `GET /` +- **Purpose**: Root health check and API information +- **Response**: Basic API status, version, and health confirmation +- **Use Case**: Quick API availability check -### **Recommendations (4)** -- `GET /recommend-news` - Recommendations by article ID -- `POST /recommend-by-query` - Recommendations by text query -- `POST /recommend-by-interests` - Recommendations by user interests -- `GET /trending` - Get trending articles +#### `GET /health` +- **Purpose**: Detailed system health and statistics +- **Response**: Vector store stats, total articles, index status, settings +- **Use Case**: System monitoring and diagnostics -### **Search & Discovery (1)** -- `POST /search` - Advanced semantic search with filters +#### `GET /stats` +- **Purpose**: Comprehensive system metrics and performance data +- **Response**: Detailed statistics including embedding stats, RSS feeds, model info +- **Use Case**: Performance monitoring and system analysis -### **AI Analysis (3)** -- `POST /analyze-article` - AI analysis of specific article -- `POST /generate-insights` - Generate AI insights from articles -- `GET /ai-status` - AI system status & capabilities +### **News Management Endpoints (2)** + +#### `POST /fetch-news` +- **Purpose**: Fetch fresh articles from all configured RSS feeds +- **Response**: Success status, articles fetched count, total articles +- **Use Case**: Manual news updates and system refresh + +#### `GET /articles` +- **Purpose**: Retrieve articles with advanced filtering and pagination +- **Parameters**: `limit`, `offset`, `source`, `category`, `date_from`, `date_to` +- **Response**: Paginated articles with metadata and filtering info +- **Use Case**: Browse articles, implement pagination, filter by criteria + +### **Recommendation Endpoints (4)** + +#### `GET /recommend-news` +- **Purpose**: Get recommendations based on a specific article ID +- **Parameters**: `article_id` (required), `top_k` (default: 5) +- **Response**: Similar articles with similarity scores +- **Use Case**: "More like this" functionality + +#### `POST /recommend-by-query` +- **Purpose**: Get recommendations based on text query +- **Body**: `{"query": "text", "top_k": 5}` +- **Response**: Relevant articles matching query semantics +- **Use Case**: Content discovery, topic-based recommendations + +#### `POST /recommend-by-interests` +- **Purpose**: Get recommendations based on user interests +- **Body**: `{"interests": ["AI", "technology"], "top_k": 10}` +- **Response**: Articles matching user interest profile +- **Use Case**: Personalized content feeds + +#### `GET /trending` +- **Purpose**: Get currently trending articles +- **Parameters**: `top_k` (default: 10) +- **Response**: Most popular/relevant recent articles +- **Use Case**: Homepage trending section, popular content + +### **Search & Discovery Endpoints (1)** + +#### `POST /search` +- **Purpose**: Advanced semantic search with multiple filters +- **Body**: `{"query": "text", "top_k": 5, "date_from": "2024-01-01", "source": "TechCrunch"}` +- **Response**: Semantically similar articles with relevance scores +- **Features**: Semantic similarity, date filtering, source filtering, content inclusion +- **Use Case**: Intelligent search, content discovery + +### **AI Analysis Endpoints (3)** + +#### `POST /analyze-article` +- **Purpose**: AI-powered analysis of a specific article +- **Body**: `{"article_id": "article_id"}` +- **Response**: AI-generated summary, sentiment analysis, key insights +- **Use Case**: Content analysis, automated insights + +#### `POST /generate-insights` +- **Purpose**: Generate AI insights from multiple recent articles +- **Body**: `{"article_count": 10}` +- **Response**: Trend analysis, topic summaries, market insights +- **Use Case**: Market research, trend analysis, content curation + +#### `GET /ai-status` +- **Purpose**: Check AI system status and capabilities +- **Response**: AI availability, model status, feature capabilities +- **Use Case**: System health check, feature availability verification ## Setup & Installation @@ -223,7 +284,7 @@ Our implementation includes: { "status": "healthy", "vector_store": { - "total_articles": 714, + "total_articles": 238, "index_dimension": 384, "index_exists": true }