docs/api-specification.md

# Crossword Puzzle API Specification

## Base URL
- Development: `http://localhost:3000/api`
- Production: `https://your-backend-domain.com/api`

## Authentication
No authentication required for this MVP version.

## Endpoints

### GET /topics
Retrieve all available topics for crossword generation.

**Response:**
```json
{
  "topics": [
    {
      "id": 1,
      "name": "Animals",
      "description": "Creatures from the animal kingdom"
    },
    {
      "id": 2,
      "name": "Science", 
      "description": "Scientific terms and concepts"
    }
  ]
}
```

**Status Codes:**
- `200 OK` - Success
- `500 Internal Server Error` - Database error

---

### POST /generate
Generate a new crossword puzzle based on selected topics and difficulty.

**Request Body:**
```json
{
  "topics": ["Animals", "Science"],
  "difficulty": "medium",
  "gridSize": 15
}
```

**Parameters:**
- `topics` (string[]): Array of topic names to include
- `difficulty` (string): "easy" | "medium" | "hard"
- `gridSize` (number, optional): Grid size (default: 15)

**Response:**
```json
{
  "puzzle": {
    "id": "puzzle_123",
    "grid": [
      [
        { "letter": "D", "number": 1, "isBlocked": false },
        { "letter": "", "number": null, "isBlocked": true }
      ]
    ],
    "clues": {
      "across": [
        {
          "number": 1,
          "clue": "Man's best friend",
          "answer": "DOG",
          "startRow": 0,
          "startCol": 0,
          "length": 3
        }
      ],
      "down": [
        {
          "number": 2,
          "clue": "Feline pet",
          "answer": "CAT", 
          "startRow": 0,
          "startCol": 2,
          "length": 3
        }
      ]
    },
    "metadata": {
      "difficulty": "medium",
      "topics": ["Animals"],
      "wordCount": 8,
      "generatedAt": "2024-01-15T10:30:00Z"
    }
  }
}
```

**Status Codes:**
- `200 OK` - Puzzle generated successfully
- `400 Bad Request` - Invalid request parameters
- `422 Unprocessable Entity` - Unable to generate puzzle with given constraints
- `500 Internal Server Error` - Generation failed

---

### POST /validate
Validate user answers against the puzzle solution.

**Request Body:**
```json
{
  "puzzleId": "puzzle_123",
  "answers": {
    "1_across": "DOG",
    "2_down": "CAT"
  }
}
```

**Response:**
```json
{
  "validation": {
    "isComplete": false,
    "correctCount": 1,
    "totalCount": 2,
    "results": {
      "1_across": {
        "correct": true,
        "expected": "DOG",
        "provided": "DOG"
      },
      "2_down": {
        "correct": false,
        "expected": "CAT",
        "provided": "CAR"
      }
    }
  }
}
```

**Status Codes:**
- `200 OK` - Validation completed
- `400 Bad Request` - Invalid puzzle ID or answers format
- `404 Not Found` - Puzzle not found
- `500 Internal Server Error` - Validation failed

---

### GET /words/:topic (Admin/Development)
Retrieve all words for a specific topic. Useful for development and debugging.

**Parameters:**
- `topic` (string): Topic name

**Response:**
```json
{
  "topic": "Animals",
  "words": [
    {
      "id": 1,
      "word": "DOG",
      "length": 3,
      "difficulty": 1,
      "clues": [
        {
          "id": 1,
          "text": "Man's best friend",
          "difficulty": 1
        }
      ]
    }
  ]
}
```

**Status Codes:**
- `200 OK` - Words retrieved
- `404 Not Found` - Topic not found
- `500 Internal Server Error` - Database error

## Error Response Format

All error responses follow this format:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid difficulty level",
    "details": {
      "field": "difficulty",
      "allowedValues": ["easy", "medium", "hard"]
    }
  }
}
```

## Rate Limiting

- Generate endpoint: 10 requests per minute per IP
- Other endpoints: 100 requests per minute per IP

## CORS Configuration

- Allowed origins: Frontend domain(s)
- Allowed methods: GET, POST, OPTIONS
- Allowed headers: Content-Type, Authorization

## Data Types

### Grid Cell
```typescript
interface GridCell {
  letter: string;        // Empty string for user input cells
  number: number | null; // Clue number if cell starts a word
  isBlocked: boolean;    // True for black squares
}
```

### Clue
```typescript
interface Clue {
  number: number;    // Clue number
  clue: string;      // Clue text
  answer: string;    // Expected answer
  startRow: number;  // Starting row in grid
  startCol: number;  // Starting column in grid
  length: number;    // Word length
}
```

### Puzzle Metadata
```typescript
interface PuzzleMetadata {
  difficulty: 'easy' | 'medium' | 'hard';
  topics: string[];
  wordCount: number;
  generatedAt: string; // ISO timestamp
}
```