mirror of
https://github.com/Dvorinka/Dash.git
synced 2026-10-28 07:41:27 +00:00
Tomas Dvorak
8afc7df53b
Backend: internal/widget registry (type metadata + Fetcher), Pi-hole v5 / AdGuard / Immich fetchers, /api/widgets/types + /api/widgets/:id/data with 30s TTL cache (failures cached too), kind+config on item create/patch. Config secrets are never logged or echoed in errors. Frontend: WidgetContent host maps config.type to a component, polls /data every 30s for server-backed types; clock renders client-side. Generic WidgetDialog builds its form from the registry's field list. Widget tiles are sortable items in both renderers. Generated with [Devin](https://devin.ai) Authored By: TDvorak <[email protected]> Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
576 lines
14 KiB
YAML
576 lines
14 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Dash API
|
|
version: 0.1.0
|
|
description: >
|
|
Single source of truth for the Dash API. The TypeScript client in
|
|
packages/api-client is generated from this file — do not hand-write
|
|
API types in the frontend.
|
|
servers:
|
|
- url: /
|
|
paths:
|
|
/api/healthz:
|
|
get:
|
|
operationId: healthz
|
|
summary: Liveness + database reachability probe
|
|
responses:
|
|
"200":
|
|
description: Service healthy
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Health"
|
|
"503":
|
|
description: Database unreachable
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Health"
|
|
|
|
/api/sections:
|
|
get:
|
|
operationId: listSections
|
|
summary: Full board — sections with nested items and urls, ordered
|
|
responses:
|
|
"200":
|
|
description: Ordered board tree
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Section"
|
|
post:
|
|
operationId: createSection
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SectionInput"
|
|
responses:
|
|
"201":
|
|
description: Created section
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Section"
|
|
|
|
/api/sections/{id}:
|
|
patch:
|
|
operationId: updateSection
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SectionPatch"
|
|
responses:
|
|
"200":
|
|
description: Updated section
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Section"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
delete:
|
|
operationId: deleteSection
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
responses:
|
|
"204":
|
|
description: Section and its items deleted
|
|
|
|
/api/sections/reorder:
|
|
post:
|
|
operationId: reorderSection
|
|
summary: Move a section between two neighbors (fractional position)
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Reorder"
|
|
responses:
|
|
"200":
|
|
description: Reordered
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Section"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
|
|
/api/items:
|
|
post:
|
|
operationId: createItem
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ItemInput"
|
|
responses:
|
|
"201":
|
|
description: Created item
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Item"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
|
|
/api/items/{id}:
|
|
patch:
|
|
operationId: updateItem
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ItemPatch"
|
|
responses:
|
|
"200":
|
|
description: Updated item
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Item"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
delete:
|
|
operationId: deleteItem
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
responses:
|
|
"204":
|
|
description: Item deleted
|
|
|
|
/api/items/{id}/icon:
|
|
post:
|
|
operationId: uploadIcon
|
|
summary: Upload an icon file; returns the stored icon reference
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required: [file]
|
|
properties:
|
|
file:
|
|
type: string
|
|
format: binary
|
|
responses:
|
|
"200":
|
|
description: Icon stored
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Item"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
|
|
/api/items/reorder:
|
|
post:
|
|
operationId: reorderItem
|
|
summary: Move an item between two neighbors, optionally across sections
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ItemReorder"
|
|
responses:
|
|
"200":
|
|
description: Reordered
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Item"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
|
|
/api/icons/{file}:
|
|
get:
|
|
operationId: getIcon
|
|
summary: Serve an uploaded icon file
|
|
parameters:
|
|
- name: file
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Icon bytes
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
|
|
/api/widgets/types:
|
|
get:
|
|
operationId: widgetTypes
|
|
summary: Widget registry metadata — drives the add-widget dialog
|
|
responses:
|
|
"200":
|
|
description: Registered widget types
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/WidgetType"
|
|
|
|
/api/widgets/{id}/data:
|
|
get:
|
|
operationId: widgetData
|
|
summary: Live data for one widget item (~30s server-side cache)
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
responses:
|
|
"200":
|
|
description: Widget payload; shape depends on config.type
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WidgetData"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"502":
|
|
description: Upstream service unreachable
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/status:
|
|
get:
|
|
operationId: getStatus
|
|
summary: Reachability of each service item's primary URL (~60s server cache)
|
|
responses:
|
|
"200":
|
|
description: Status map keyed by item id
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Status"
|
|
|
|
/api/settings:
|
|
get:
|
|
operationId: getSettings
|
|
responses:
|
|
"200":
|
|
description: All settings as key/value map
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
put:
|
|
operationId: putSettings
|
|
summary: Merge settings (keys not sent are preserved)
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
responses:
|
|
"200":
|
|
description: Full settings map after merge
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
/api/export:
|
|
get:
|
|
operationId: exportBoard
|
|
summary: Full JSON backup (sections, items, urls, settings)
|
|
responses:
|
|
"200":
|
|
description: Board export
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Export"
|
|
|
|
/api/import:
|
|
post:
|
|
operationId: importBoard
|
|
summary: Replace board state from an export payload
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Export"
|
|
responses:
|
|
"200":
|
|
description: Imported board tree
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Section"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
|
|
components:
|
|
parameters:
|
|
id:
|
|
name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
|
|
responses:
|
|
NotFound:
|
|
description: Not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
BadRequest:
|
|
description: Invalid input
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
schemas:
|
|
Health:
|
|
type: object
|
|
required: [status]
|
|
properties:
|
|
status:
|
|
type: string
|
|
example: ok
|
|
Error:
|
|
type: object
|
|
required: [error]
|
|
properties:
|
|
error:
|
|
type: string
|
|
Url:
|
|
type: object
|
|
required: [id, url, label]
|
|
properties:
|
|
id:
|
|
type: string
|
|
url:
|
|
type: string
|
|
format: uri
|
|
label:
|
|
type: string
|
|
description: Tag such as "local" / "external" or a custom label
|
|
position:
|
|
type: number
|
|
UrlInput:
|
|
type: object
|
|
required: [url]
|
|
properties:
|
|
url:
|
|
type: string
|
|
format: uri
|
|
label:
|
|
type: string
|
|
default: ""
|
|
Item:
|
|
type: object
|
|
required: [id, sectionId, kind, name, position, urls]
|
|
properties:
|
|
id:
|
|
type: string
|
|
sectionId:
|
|
type: string
|
|
kind:
|
|
type: string
|
|
enum: [service, widget]
|
|
name:
|
|
type: string
|
|
icon:
|
|
type: string
|
|
description: "/api/icons/<file> path or remote URL; empty = letter tile"
|
|
position:
|
|
type: number
|
|
config:
|
|
type: object
|
|
nullable: true
|
|
additionalProperties: true
|
|
description: Widget config (Phase 2); null for services
|
|
urls:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Url"
|
|
ItemInput:
|
|
type: object
|
|
required: [sectionId, name]
|
|
properties:
|
|
sectionId:
|
|
type: string
|
|
kind:
|
|
type: string
|
|
enum: [service, widget]
|
|
default: service
|
|
name:
|
|
type: string
|
|
icon:
|
|
type: string
|
|
config:
|
|
type: object
|
|
nullable: true
|
|
additionalProperties: true
|
|
description: Widget config — keys defined by the widget type's fields
|
|
urls:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/UrlInput"
|
|
ItemPatch:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
icon:
|
|
type: string
|
|
config:
|
|
type: object
|
|
nullable: true
|
|
additionalProperties: true
|
|
urls:
|
|
type: array
|
|
description: Full replacement of the item's URL list
|
|
items:
|
|
$ref: "#/components/schemas/UrlInput"
|
|
Section:
|
|
type: object
|
|
required: [id, name, position, collapsed, items]
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
position:
|
|
type: number
|
|
collapsed:
|
|
type: boolean
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Item"
|
|
SectionInput:
|
|
type: object
|
|
required: [name]
|
|
properties:
|
|
name:
|
|
type: string
|
|
SectionPatch:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
collapsed:
|
|
type: boolean
|
|
Reorder:
|
|
type: object
|
|
required: [id]
|
|
properties:
|
|
id:
|
|
type: string
|
|
beforeId:
|
|
type: string
|
|
description: Neighbor now before the moved entity; null if first
|
|
afterId:
|
|
type: string
|
|
description: Neighbor now after the moved entity; null if last
|
|
ItemReorder:
|
|
allOf:
|
|
- $ref: "#/components/schemas/Reorder"
|
|
- type: object
|
|
properties:
|
|
sectionId:
|
|
type: string
|
|
description: Target section (defaults to current)
|
|
Status:
|
|
type: object
|
|
required: [status]
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [up, down]
|
|
latencyMs:
|
|
type: integer
|
|
checkedAt:
|
|
type: string
|
|
format: date-time
|
|
WidgetField:
|
|
type: object
|
|
required: [key, label]
|
|
properties:
|
|
key:
|
|
type: string
|
|
label:
|
|
type: string
|
|
secret:
|
|
type: boolean
|
|
description: Render as password input; never logged
|
|
placeholder:
|
|
type: string
|
|
required:
|
|
type: boolean
|
|
WidgetType:
|
|
type: object
|
|
required: [type, name, fields]
|
|
properties:
|
|
type:
|
|
type: string
|
|
name:
|
|
type: string
|
|
description:
|
|
type: string
|
|
local:
|
|
type: boolean
|
|
description: Client-rendered (e.g. clock); no /data fetch needed
|
|
fields:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/WidgetField"
|
|
WidgetData:
|
|
type: object
|
|
required: [data]
|
|
properties:
|
|
data:
|
|
type: object
|
|
additionalProperties: true
|
|
fetchedAt:
|
|
type: string
|
|
format: date-time
|
|
Export:
|
|
type: object
|
|
required: [version, sections]
|
|
properties:
|
|
version:
|
|
type: integer
|
|
settings:
|
|
type: object
|
|
additionalProperties: true
|
|
sections:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Section"
|