initial

2025-12-22 14:47:25 -05:00
parent d4e859f9a7
commit 00e9eb8986
81 changed files with 13933 additions and 0 deletions
--- a/API_EXAMPLES.md
+++ b/API_EXAMPLES.md
@@ -0,0 +1,233 @@
+# API Examples for Bulk Operations
+
+## Creating Categories
+
+Categories can be created using the existing categories API:
+
+### Create a Single Category
+
+```bash
+curl -X POST http://localhost:5000/api/categories \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Science"
+  }'
+```
+
+### Create Multiple Categories
+
+```bash
+# History
+curl -X POST http://localhost:5000/api/categories \
+  -H "Content-Type: application/json" \
+  -d '{"name": "History"}'
+
+# Geography
+curl -X POST http://localhost:5000/api/categories \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Geography"}'
+
+# Sports
+curl -X POST http://localhost:5000/api/categories \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Sports"}'
+```
+
+## Bulk Creating Questions
+
+Use the new bulk import endpoint to create many questions at once:
+
+```bash
+curl -X POST http://localhost:5000/api/questions/bulk \
+  -H "Content-Type: application/json" \
+  -d '{
+    "questions": [
+      {
+        "question_content": "What is the capital of France?",
+        "answer": "Paris",
+        "category": "Geography",
+        "type": "text"
+      },
+      {
+        "question_content": "Who painted the Mona Lisa?",
+        "answer": "Leonardo da Vinci",
+        "category": "Art",
+        "type": "text"
+      },
+      {
+        "question_content": "What year did World War II end?",
+        "answer": "1945",
+        "category": "History",
+        "type": "text"
+      },
+      {
+        "question_content": "What is the chemical symbol for gold?",
+        "answer": "Au",
+        "category": "Science",
+        "type": "text"
+      },
+      {
+        "question_content": "How many players are on a soccer team?",
+        "answer": "11",
+        "category": "Sports",
+        "type": "text"
+      }
+    ]
+  }'
+```
+
+## Python Script Example
+
+```python
+import requests
+
+API_BASE_URL = "http://localhost:5000/api"
+
+# Create categories
+categories = ["Science", "History", "Geography", "Sports", "Entertainment", "Art"]
+for category in categories:
+    response = requests.post(
+        f"{API_BASE_URL}/categories",
+        json={"name": category}
+    )
+    print(f"Created category: {category}")
+
+# Bulk create questions
+questions = [
+    {
+        "question_content": "What is the capital of France?",
+        "answer": "Paris",
+        "category": "Geography",
+        "type": "text"
+    },
+    {
+        "question_content": "Who painted the Mona Lisa?",
+        "answer": "Leonardo da Vinci",
+        "category": "Art",
+        "type": "text"
+    },
+    {
+        "question_content": "What year did World War II end?",
+        "answer": "1945",
+        "category": "History",
+        "type": "text"
+    },
+    {
+        "question_content": "What is H2O?",
+        "answer": "Water",
+        "category": "Science",
+        "type": "text"
+    },
+    {
+        "question_content": "How many rings are in the Olympic logo?",
+        "answer": "5",
+        "category": "Sports",
+        "type": "text"
+    }
+]
+
+response = requests.post(
+    f"{API_BASE_URL}/questions/bulk",
+    json={"questions": questions}
+)
+
+result = response.json()
+print(f"Created {result['created']} questions")
+if result['errors']:
+    print(f"Errors: {result['errors']}")
+```
+
+## JavaScript/Node.js Example
+
+```javascript
+const API_BASE_URL = "http://localhost:5000/api";
+
+// Create categories
+const categories = ["Science", "History", "Geography", "Sports", "Entertainment", "Art"];
+for (const category of categories) {
+  await fetch(`${API_BASE_URL}/categories`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name: category })
+  });
+  console.log(`Created category: ${category}`);
+}
+
+// Bulk create questions
+const questions = [
+  {
+    question_content: "What is the capital of France?",
+    answer: "Paris",
+    category: "Geography",
+    type: "text"
+  },
+  {
+    question_content: "Who painted the Mona Lisa?",
+    answer: "Leonardo da Vinci",
+    category: "Art",
+    type: "text"
+  },
+  // ... more questions
+];
+
+const response = await fetch(`${API_BASE_URL}/questions/bulk`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ questions })
+});
+
+const result = await response.json();
+console.log(`Created ${result.created} questions`);
+```
+
+## Response Format
+
+### Bulk Create Success Response
+
+```json
+{
+  "message": "Successfully created 5 questions",
+  "created": 5,
+  "errors": [],
+  "questions": [
+    {
+      "id": 1,
+      "type": "text",
+      "question_content": "What is the capital of France?",
+      "answer": "Paris",
+      "category": "Geography",
+      "image_path": null,
+      "created_at": "2024-12-08T12:00:00"
+    }
+    // ... more questions
+  ]
+}
+```
+
+### With Errors
+
+```json
+{
+  "message": "Successfully created 3 questions",
+  "created": 3,
+  "errors": [
+    {
+      "index": 1,
+      "error": "question_content is required"
+    },
+    {
+      "index": 4,
+      "error": "answer is required"
+    }
+  ],
+  "questions": [...]
+}
+```
+
+## Notes
+
+- The bulk import endpoint does **not** support image questions
+- Categories must be created before using them in questions (or use existing ones)
+- The `type` field defaults to "text" if not specified
+- The `category` field is optional
+- Invalid questions in the bulk request will be skipped, and their errors will be reported