# API Endpoints for Frontend Compatibility

This document defines the minimal backend surface expected by the Vue frontend. Default base path is `/api`; responses are JSON with `Content-Type: application/json`.

## POST /api/randomize
- **Purpose:** Produce a randomized Dota 2 build and optionally return the full data sets used for rendering.
- **Request body:**
  - `includeSkills` (boolean) — include a skill build suggestion.
  - `includeAspect` (boolean) — include an aspect suggestion.
  - `itemsCount` (number) — how many items to return (UI offers 3–6).
- **Response 200 body:**
  - `hero` — object `{ id: string; name: string; primary: string; }`.
  - `items` — array of `{ id: string; name: string; }` with length `itemsCount` (also used to hydrate cached items if you return the full pool).
  - `skillBuild` (optional) — `{ id: string; name: string; description?: string; }` when `includeSkills` is true.
  - `aspect` (optional) — string when `includeAspect` is true.
  - `heroes` (optional) — full hero list to cache client-side; same shape as `hero`.
  - `skillBuilds` (optional) — full skill build list; same shape as `skillBuild`.
  - `aspects` (optional) — array of strings.
- **Example request:**
```json
{
  "includeSkills": true,
  "includeAspect": false,
  "itemsCount": 6
}
```
- **Example response:**
```json
{
  "hero": { "id": "pudge", "name": "Pudge", "primary": "strength" },
  "items": [
    { "id": "blink", "name": "Blink Dagger" },
    { "id": "bkb", "name": "Black King Bar" }
  ],
  "skillBuild": { "id": "hookdom", "name": "Hook/Rot Max", "description": "Max hook, then rot; early Flesh Heap." },
  "heroes": [{ "id": "axe", "name": "Axe", "primary": "strength" }],
  "skillBuilds": [{ "id": "support", "name": "Support" }],
  "aspects": ["Heroic Might"]
}
```

## Error Handling
- Use standard HTTP status codes (400 invalid input, 500 server error).
- Error payload shape:
```json
{ "message": "Failed to load random build" }
```
- The UI surfaces `message` directly; keep it user-friendly.

## Implementation Notes
- Ensure deterministic constraints: unique `id` per entity and avoid empty arrays when `includeSkills`/`includeAspect` are true.
- If backing data is static, you may return `heroes/items/skillBuilds/aspects` once per request; the frontend caches them after the first successful call.