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:

{
  "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:

{
  "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:

{
  "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:

{
  "puzzleId": "puzzle_123",
  "answers": {
    "1_across": "DOG",
    "2_down": "CAT"
  }
}

Response:

{
  "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:

{
  "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:

{
  "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

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

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

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