triviathang/API_EXAMPLES.md

# 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