dota-random-builds-front/API.md

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:

{
  "includeSkills": true,
  "includeAspect": false,
  "itemsCount": 6
}

• Example response:

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

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