john-okeefe
44a0f8c7a4
The scattered scan-settings JSON routes are superseded by the new admin-only /api/system/settings pair backed by the SettingsRegistry (introduced in885f6d8/bc47450). - Rewrite system/settings.md around GET/PUT /api/system/settings: SettingEntry metadata shape (type, min/max, requires_restart, category, group, is_default), type-aware validation rules, and the full tunable-setting catalog (scanner, general, security, api, sync, performance) with defaults, ranges, and restart requirements - Note the legacy /api/libraries/scan-settings routes as back-compat only (they now refresh the registry cache on write) - Add system/config.md for GET/PUT /api/system/config: raw key/value system configuration (e.g. base_url), including validation notes and guidance to prefer the typed settings endpoint for registry keys
78 lines
2.2 KiB
Markdown
78 lines
2.2 KiB
Markdown
# System Config API
|
|
|
|
## Overview
|
|
|
|
Raw key/value system configuration storage (backed by the `system_config` table). Unlike the typed [System Settings API](settings.md), this endpoint reads and writes arbitrary config keys as plain strings — including keys without registry metadata, such as `base_url`.
|
|
|
|
**Base URL**: `/api/system`
|
|
**Authentication**: Admin JWT token required
|
|
**Content-Type**: `application/json`
|
|
|
|
---
|
|
|
|
## Endpoints
|
|
|
|
### Get System Configuration
|
|
|
|
Retrieve all system configuration entries as a flat key/value map.
|
|
|
|
**Endpoint**: `GET /api/system/config`
|
|
|
|
**Authentication**: Admin role required
|
|
|
|
**Response**: **200 OK**
|
|
|
|
```json
|
|
{
|
|
"base_url": "http://192.168.1.100:8765",
|
|
"default_timezone": "America/New_York"
|
|
}
|
|
```
|
|
|
|
**Example**:
|
|
|
|
```bash
|
|
curl -X GET https://bookhoard.example.com/api/system/config \
|
|
-H "Authorization: Bearer <admin_token>"
|
|
```
|
|
|
|
---
|
|
|
|
### Update System Configuration
|
|
|
|
Update one or more config values.
|
|
|
|
**Endpoint**: `PUT /api/system/config`
|
|
|
|
**Authentication**: Admin role required
|
|
|
|
**Request Body**: a flat map of keys to string values. Only the supplied keys are updated.
|
|
|
|
```json
|
|
{
|
|
"base_url": "https://bookhoard.example.com"
|
|
}
|
|
```
|
|
|
|
**Validation**: values for known keys are validated where applicable — for example, `default_timezone` must be a valid IANA timezone (`time.LoadLocation`); invalid values return `400` without persisting.
|
|
|
|
**Response**: **200 OK** on success; `400` (invalid value/format), `401`, `403`, `500` on failure.
|
|
|
|
**Example**:
|
|
|
|
```bash
|
|
curl -X PUT https://bookhoard.example.com/api/system/config \
|
|
-H "Authorization: Bearer <admin_token>" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"base_url": "https://bookhoard.example.com"}'
|
|
```
|
|
|
|
> **Note:** settings that appear in the typed settings registry (e.g. `default_timezone`) are better managed through [`PUT /api/system/settings`](settings.md), which also returns metadata and reload hints. Writes through either endpoint refresh the shared registry cache.
|
|
|
|
---
|
|
|
|
## Related Endpoints
|
|
|
|
- [System Settings API](settings.md) — typed, validated tunable settings with metadata
|
|
- `GET /api/devices/:id/sidecar` — device setup config derived from system config (see [Devices API](../devices/))
|