mirror of
https://github.com/Lissy93/dashy.git
synced 2026-07-30 11:06:09 -04:00
112 lines
5.2 KiB
Markdown
112 lines
5.2 KiB
Markdown
# REST API
|
|
|
|
Dashy includes an optional REST API, for reading and writing your config programmatically — from the command line, scripts or third-party applications. It covers whole config files, as well as individual sections and items.
|
|
|
|
> [!NOTE]
|
|
> The API is served by Dashy's Node server, so it's available with Docker and bare-metal deployments, but not on static hosting providers (Netlify, Vercel, EdgeOne, CDN).
|
|
|
|
## Enabling the API
|
|
|
|
The API is disabled by default. To enable it, set the `ENABLE_API` environmental variable to `true`. For example, with Docker Compose:
|
|
|
|
```yaml
|
|
environment:
|
|
- ENABLE_API=true
|
|
```
|
|
|
|
Or with `docker run`, pass `-e ENABLE_API=true`. While disabled, all `/api/*` requests return a 404.
|
|
|
|
## Authentication
|
|
|
|
By default, the API uses Dashy's existing [server-side authentication](/docs/authentication.md). Read endpoints require any authenticated user, and write endpoints require an admin. If no auth is configured, the API is open — the same as Dashy's other endpoints.
|
|
|
|
```bash
|
|
# With HTTP Basic Auth (ENABLE_HTTP_AUTH or BASIC_AUTH_USERNAME / BASIC_AUTH_PASSWORD)
|
|
curl -u alice:hunter2 http://localhost:8080/api/config
|
|
|
|
# With OIDC / Keycloak, pass your ID token
|
|
curl -H 'Authorization: Bearer <id-token>' http://localhost:8080/api/config
|
|
```
|
|
|
|
### API token
|
|
|
|
If you have no auth configured, or would prefer a dedicated credential for the API, set the `API_TOKEN` environmental variable and send it as a bearer token. A valid token grants full (admin) access, and works alongside any other configured auth method.
|
|
|
|
```yaml
|
|
environment:
|
|
- ENABLE_API=true
|
|
- API_TOKEN=your-long-random-secret
|
|
```
|
|
|
|
```bash
|
|
curl -H 'Authorization: Bearer your-long-random-secret' http://localhost:8080/api/config
|
|
```
|
|
|
|
> [!NOTE]
|
|
> Setting `API_TOKEN` also secures the API on deployments that have no other auth — anonymous requests are then rejected. Use a long, random value (e.g. `openssl rand -hex 32`) and only send it over HTTPS. The token applies to the API only, not Dashy's other endpoints.
|
|
|
|
## Endpoints
|
|
|
|
`:filename` is any YAML config file in your user-data directory (e.g. `conf.yml`, or a sub-page like `home-lab.yml`). `:key` is one of the top-level config keys: `pageInfo`, `appConfig`, `sections` or `pages`.
|
|
|
|
**Method** | **Path** | **Description**
|
|
--- | --- | ---
|
|
`GET` | `/api/config` | List config files
|
|
`GET` | `/api/config/:filename` | Get a full config file, as JSON
|
|
`PUT` | `/api/config/:filename` | Replace a full config file
|
|
`GET` | `/api/config/:filename/:key` | Get a top-level key
|
|
`PUT` | `/api/config/:filename/:key` | Replace a top-level key
|
|
`POST` | `/api/config/:filename/sections` | Add a section (`name` required)
|
|
`GET` | `/api/config/:filename/sections/:sid` | Get a section
|
|
`PATCH` | `/api/config/:filename/sections/:sid` | Update fields on a section
|
|
`DELETE` | `/api/config/:filename/sections/:sid` | Delete a section
|
|
`GET` | `/api/config/:filename/sections/:sid/items` | List a section's items
|
|
`POST` | `/api/config/:filename/sections/:sid/items` | Add an item (`title` required)
|
|
`GET` | `/api/config/:filename/sections/:sid/items/:iid` | Get an item
|
|
`PATCH` | `/api/config/:filename/sections/:sid/items/:iid` | Update fields on an item
|
|
`DELETE` | `/api/config/:filename/sections/:sid/items/:iid` | Delete an item
|
|
|
|
All bodies are JSON. Errors return `{ "success": false, "message": "..." }` with an appropriate status code (400 bad input, 401/403 auth, 404 not found).
|
|
|
|
### Addressing Sections and Items
|
|
|
|
`:sid` and `:iid` can be either a zero-based index (`0`, `1`, ...) or an exact match on the section's `name` / item's `title` (URL-encoded). If multiple entries share a name, the first match wins. A section literally named `2` can only be addressed by index.
|
|
|
|
### Updating
|
|
|
|
`PATCH` does a shallow merge: only the fields you send are changed, but nested values (like a section's `items` array) are replaced wholesale if included. `PUT` replaces the target entirely.
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# List config files
|
|
curl http://localhost:8080/api/config
|
|
|
|
# Get your main config as JSON
|
|
curl http://localhost:8080/api/config/conf.yml
|
|
|
|
# Add an item to the first section
|
|
curl -X POST -H 'Content-Type: application/json' \
|
|
-d '{"title": "Grafana", "url": "https://grafana.local", "icon": "hl-grafana"}' \
|
|
http://localhost:8080/api/config/conf.yml/sections/0/items
|
|
|
|
# Rename a section
|
|
curl -X PATCH -H 'Content-Type: application/json' \
|
|
-d '{"name": "Monitoring"}' \
|
|
'http://localhost:8080/api/config/conf.yml/sections/Old%20Name'
|
|
|
|
# Update the theme
|
|
curl -X PUT -H 'Content-Type: application/json' \
|
|
-d '{"theme": "nord-frost"}' \
|
|
http://localhost:8080/api/config/conf.yml/appConfig
|
|
```
|
|
|
|
After modifying your config, refresh the page to see changes.
|
|
|
|
## Limitations & Notes
|
|
|
|
- Writes re-serialize the YAML file, so comments, anchors and custom formatting are discarded (the same applies to saving via the UI). A timestamped backup is saved to `user-data/config-backups/` before every write, unless `DISABLE_CONFIG_BACKUPS=true`
|
|
- Writes to `conf.yml` are validated against [the schema](https://github.com/Lissy93/dashy/blob/master/src/utils/config/ConfigSchema.json) and rejected if invalid. Sub-page files are not schema-validated, since they may contain only a subset of fields
|
|
- Config files are capped at 256 KB
|
|
- Concurrent writes are last-write-wins; there is no locking or optimistic concurrency
|