53 lines
2.3 KiB
Markdown
53 lines
2.3 KiB
Markdown
|
# 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.
|