Initial commit

dota-random-builds-back/API.md

@@ -0,0 +1,52 @@
+# 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.