476 lines
15 KiB
YAML
476 lines
15 KiB
YAML
|
openapi: "3.0.3"
|
|||
|
|
info:
|
|||
|
|
title: OTA Manifest — Daemon API
|
|||
|
|
description: |
|
|||
|
|
Device-side REST API for the OTA update platform.
|
|||
|
|
Each daemon (`mcd`) calls these endpoints to register, heartbeat,
|
|||
|
|
poll for updates, download artefacts, and report progress.
|
|||
|
|
|
|||
|
|
**10 Mbps bandwidth design points:**
|
|||
|
|
- Downloads are **rate-limited** (~25 KB/s per connection) and **gated** (max 50 concurrent).
|
|||
|
|
- The download endpoint supports **HTTP Range** (`206 Partial Content`) for resumable transfers.
|
|||
|
|
- `check-update` returns a delta patch when available to minimise bytes on the wire.
|
|||
|
|
version: "1.0.0"
|
|||
|
|
contact:
|
|||
|
|
name: Quanta OTA Team
|
|||
|
|
|
|||
|
|
servers:
|
|||
|
|
- url: http://localhost:8080/api/v1
|
|||
|
|
description: Local development server
|
|||
|
|
|
|||
|
|
tags:
|
|||
|
|
- name: Device
|
|||
|
|
description: Registration, heartbeat, and update checking
|
|||
|
|
- name: Package
|
|||
|
|
description: Artefact download
|
|||
|
|
- name: Deployment
|
|||
|
|
description: Lifecycle status reporting
|
|||
|
|
|
|||
|
|
# ─────────────────────────────────────────────────────────────
|
|||
|
|
# Paths
|
|||
|
|
# ─────────────────────────────────────────────────────────────
|
|||
|
|
paths:
|
|||
|
|
|
|||
|
|
# ═══ Device ═══
|
|||
|
|
|
|||
|
|
/devices/register:
|
|||
|
|
post:
|
|||
|
|
tags: [Device]
|
|||
|
|
summary: Register or refresh a device
|
|||
|
|
description: |
|
|||
|
|
Called by the daemon on startup. If the `deviceId` already exists
|
|||
|
|
this is an upsert — all fields are updated and `lastHeartbeat` is
|
|||
|
|
refreshed.
|
|||
|
|
operationId: registerDevice
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
$ref: "#/components/schemas/RegisterDeviceRequest"
|
|||
|
|
example:
|
|||
|
|
deviceId: "mcd-7a3f-001"
|
|||
|
|
ipAddress: "192.168.1.42"
|
|||
|
|
hostname: "gateway-east-01"
|
|||
|
|
os: "Debian 12"
|
|||
|
|
currentVersion: "1.2.0"
|
|||
|
|
groupName: "east-region"
|
|||
|
|
responses:
|
|||
|
|
"200":
|
|||
|
|
description: Device registered or updated
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
$ref: "#/components/schemas/Device"
|
|||
|
|
example:
|
|||
|
|
id: 1
|
|||
|
|
deviceId: "mcd-7a3f-001"
|
|||
|
|
ipAddress: "192.168.1.42"
|
|||
|
|
hostname: "gateway-east-01"
|
|||
|
|
os: "Debian 12"
|
|||
|
|
currentVersion: "1.2.0"
|
|||
|
|
status: "online"
|
|||
|
|
groupName: "east-region"
|
|||
|
|
lastHeartbeat: "2026-07-03T10:30:00Z"
|
|||
|
|
createdAt: "2026-07-03T10:30:00Z"
|
|||
|
|
updatedAt: "2026-07-03T10:30:00Z"
|
|||
|
|
"400":
|
|||
|
|
$ref: "#/components/responses/BadRequest"
|
|||
|
|
|
|||
|
|
/devices/heartbeat:
|
|||
|
|
post:
|
|||
|
|
tags: [Device]
|
|||
|
|
summary: Send periodic heartbeat
|
|||
|
|
description: |
|
|||
|
|
Called by the daemon every 30–60 s. Keeps the device marked `online`
|
|||
|
|
and updates the `currentVersion` so the server always knows which
|
|||
|
|
version each device is running.
|
|||
|
|
operationId: heartbeat
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
$ref: "#/components/schemas/HeartbeatRequest"
|
|||
|
|
example:
|
|||
|
|
deviceId: "mcd-7a3f-001"
|
|||
|
|
currentVersion: "1.2.0"
|
|||
|
|
status: "online"
|
|||
|
|
responses:
|
|||
|
|
"200":
|
|||
|
|
description: Heartbeat acknowledged
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
$ref: "#/components/schemas/StatusResponse"
|
|||
|
|
"400":
|
|||
|
|
$ref: "#/components/responses/BadRequest"
|
|||
|
|
|
|||
|
|
/devices/check-update:
|
|||
|
|
get:
|
|||
|
|
tags: [Device]
|
|||
|
|
summary: Check whether an update is pending for this device
|
|||
|
|
description: |
|
|||
|
|
Polled by the daemon on a configurable interval (e.g. every 5 min).
|
|||
|
|
When `hasUpdate` is `true` the daemon should proceed to download the
|
|||
|
|
referenced artefact and then POST to `/deployments/{id}/status` as the
|
|||
|
|
install progresses.
|
|||
|
|
operationId: checkUpdate
|
|||
|
|
parameters:
|
|||
|
|
- name: deviceId
|
|||
|
|
in: query
|
|||
|
|
required: true
|
|||
|
|
schema:
|
|||
|
|
type: string
|
|||
|
|
description: The device's unique identifier
|
|||
|
|
example: "mcd-7a3f-001"
|
|||
|
|
responses:
|
|||
|
|
"200":
|
|||
|
|
description: Update status for the device
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
$ref: "#/components/schemas/CheckUpdateResponse"
|
|||
|
|
examples:
|
|||
|
|
hasUpdate:
|
|||
|
|
summary: Update available
|
|||
|
|
value:
|
|||
|
|
hasUpdate: true
|
|||
|
|
artefactId: 5
|
|||
|
|
version: "1.3.0"
|
|||
|
|
fileSize: 4194304
|
|||
|
|
sha256Hash: "a1b2c3d4e5f6..."
|
|||
|
|
downloadUrl: "/api/v1/packages/download/5"
|
|||
|
|
noUpdate:
|
|||
|
|
summary: No update needed
|
|||
|
|
value:
|
|||
|
|
hasUpdate: false
|
|||
|
|
"400":
|
|||
|
|
$ref: "#/components/responses/BadRequest"
|
|||
|
|
|
|||
|
|
# ═══ Package ═══
|
|||
|
|
|
|||
|
|
/packages/download/{id}:
|
|||
|
|
get:
|
|||
|
|
tags: [Package]
|
|||
|
|
summary: Download an artefact (full or delta patch)
|
|||
|
|
description: |
|
|||
|
|
Serves the artefact file with **per-connection bandwidth throttling**
|
|||
|
|
(~25 KB/s). Supports **HTTP Range** requests so interrupted downloads
|
|||
|
|
can be resumed via `Range: bytes=<offset>-`.
|
|||
|
|
|
|||
|
|
**Headers returned:**
|
|||
|
|
- `Content-Disposition: attachment; filename="<name>"`
|
|||
|
|
- `X-Checksum-SHA256: <hex>` — validate the file after download
|
|||
|
|
- `Accept-Ranges: bytes`
|
|||
|
|
- `Content-Length: <bytes>`
|
|||
|
|
|
|||
|
|
**Query parameters** are optional but recommended — they let the
|
|||
|
|
server track each device's download progress.
|
|||
|
|
operationId: downloadPackage
|
|||
|
|
parameters:
|
|||
|
|
- name: id
|
|||
|
|
in: path
|
|||
|
|
required: true
|
|||
|
|
schema:
|
|||
|
|
type: integer
|
|||
|
|
format: int64
|
|||
|
|
description: Artefact ID (from `check-update` response)
|
|||
|
|
example: 5
|
|||
|
|
- name: deviceId
|
|||
|
|
in: query
|
|||
|
|
required: false
|
|||
|
|
schema:
|
|||
|
|
type: string
|
|||
|
|
description: Device identifier for progress tracking
|
|||
|
|
example: "mcd-7a3f-001"
|
|||
|
|
- name: deploymentId
|
|||
|
|
in: query
|
|||
|
|
required: false
|
|||
|
|
schema:
|
|||
|
|
type: integer
|
|||
|
|
format: int64
|
|||
|
|
description: Deployment ID for progress tracking
|
|||
|
|
example: 3
|
|||
|
|
responses:
|
|||
|
|
"200":
|
|||
|
|
description: Full artefact file
|
|||
|
|
headers:
|
|||
|
|
Content-Disposition:
|
|||
|
|
schema:
|
|||
|
|
type: string
|
|||
|
|
description: Attachment filename
|
|||
|
|
X-Checksum-SHA256:
|
|||
|
|
schema:
|
|||
|
|
type: string
|
|||
|
|
description: SHA-256 hex digest of the file
|
|||
|
|
Accept-Ranges:
|
|||
|
|
schema:
|
|||
|
|
type: string
|
|||
|
|
example: bytes
|
|||
|
|
content:
|
|||
|
|
application/octet-stream:
|
|||
|
|
schema:
|
|||
|
|
type: string
|
|||
|
|
format: binary
|
|||
|
|
"206":
|
|||
|
|
description: Partial content (resumed download)
|
|||
|
|
headers:
|
|||
|
|
Content-Range:
|
|||
|
|
schema:
|
|||
|
|
type: string
|
|||
|
|
example: "bytes 1048576-4194303/4194304"
|
|||
|
|
content:
|
|||
|
|
application/octet-stream:
|
|||
|
|
schema:
|
|||
|
|
type: string
|
|||
|
|
format: binary
|
|||
|
|
"404":
|
|||
|
|
$ref: "#/components/responses/NotFound"
|
|||
|
|
"503":
|
|||
|
|
description: Server at download capacity — retry later
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|||
|
|
example:
|
|||
|
|
error: "Server at capacity. Please retry later."
|
|||
|
|
|
|||
|
|
# ═══ Deployment ═══
|
|||
|
|
|
|||
|
|
/deployments/{id}/status:
|
|||
|
|
post:
|
|||
|
|
tags: [Deployment]
|
|||
|
|
summary: Report deployment status for a single device
|
|||
|
|
description: |
|
|||
|
|
Called by the daemon at each lifecycle transition:
|
|||
|
|
|
|||
|
|
1. `downloading` — started the download
|
|||
|
|
2. `downloaded` — download complete (may be omitted for small files)
|
|||
|
|
3. `verifying` — checking SHA-256 hash
|
|||
|
|
4. `installing` — applying the update
|
|||
|
|
5. `completed` — update applied, device running new version
|
|||
|
|
6. `failed` — unrecoverable error (set `error` field)
|
|||
|
|
|
|||
|
|
The server tracks these transitions per-device so operators can
|
|||
|
|
monitor rollout progress.
|
|||
|
|
operationId: updateDeploymentStatus
|
|||
|
|
parameters:
|
|||
|
|
- name: id
|
|||
|
|
in: path
|
|||
|
|
required: true
|
|||
|
|
schema:
|
|||
|
|
type: integer
|
|||
|
|
format: int64
|
|||
|
|
description: Deployment ID
|
|||
|
|
example: 3
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
$ref: "#/components/schemas/DeploymentStatusRequest"
|
|||
|
|
examples:
|
|||
|
|
downloading:
|
|||
|
|
value:
|
|||
|
|
deviceId: "mcd-7a3f-001"
|
|||
|
|
status: "downloading"
|
|||
|
|
completed:
|
|||
|
|
value:
|
|||
|
|
deviceId: "mcd-7a3f-001"
|
|||
|
|
status: "completed"
|
|||
|
|
failed:
|
|||
|
|
value:
|
|||
|
|
deviceId: "mcd-7a3f-001"
|
|||
|
|
status: "failed"
|
|||
|
|
error: "SHA256 mismatch: expected a1b2.. got x9y0.."
|
|||
|
|
responses:
|
|||
|
|
"200":
|
|||
|
|
description: Status recorded
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
$ref: "#/components/schemas/StatusResponse"
|
|||
|
|
"400":
|
|||
|
|
$ref: "#/components/responses/BadRequest"
|
|||
|
|
|
|||
|
|
# ─────────────────────────────────────────────────────────────
|
|||
|
|
# Component Schemas
|
|||
|
|
# ─────────────────────────────────────────────────────────────
|
|||
|
|
components:
|
|||
|
|
|
|||
|
|
schemas:
|
|||
|
|
|
|||
|
|
# -- Requests --
|
|||
|
|
|
|||
|
|
RegisterDeviceRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [deviceId]
|
|||
|
|
properties:
|
|||
|
|
deviceId:
|
|||
|
|
type: string
|
|||
|
|
maxLength: 256
|
|||
|
|
description: Unique device identifier (set by daemon config)
|
|||
|
|
ipAddress:
|
|||
|
|
type: string
|
|||
|
|
description: Device IP at registration time
|
|||
|
|
hostname:
|
|||
|
|
type: string
|
|||
|
|
description: OS hostname
|
|||
|
|
os:
|
|||
|
|
type: string
|
|||
|
|
description: Operating system name and version
|
|||
|
|
currentVersion:
|
|||
|
|
type: string
|
|||
|
|
description: Currently installed client version
|
|||
|
|
groupName:
|
|||
|
|
type: string
|
|||
|
|
description: Logical group for targeted rollouts (defaults to "default")
|
|||
|
|
|
|||
|
|
HeartbeatRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [deviceId]
|
|||
|
|
properties:
|
|||
|
|
deviceId:
|
|||
|
|
type: string
|
|||
|
|
maxLength: 256
|
|||
|
|
currentVersion:
|
|||
|
|
type: string
|
|||
|
|
description: Currently running version
|
|||
|
|
status:
|
|||
|
|
type: string
|
|||
|
|
enum: [online, offline, upgrading]
|
|||
|
|
default: online
|
|||
|
|
|
|||
|
|
DeploymentStatusRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [deviceId, status]
|
|||
|
|
properties:
|
|||
|
|
deviceId:
|
|||
|
|
type: string
|
|||
|
|
description: Device identifier
|
|||
|
|
status:
|
|||
|
|
type: string
|
|||
|
|
enum:
|
|||
|
|
- downloading
|
|||
|
|
- downloaded
|
|||
|
|
- verifying
|
|||
|
|
- installing
|
|||
|
|
- completed
|
|||
|
|
- failed
|
|||
|
|
error:
|
|||
|
|
type: string
|
|||
|
|
description: Error description (only meaningful when status = "failed")
|
|||
|
|
|
|||
|
|
# -- Responses --
|
|||
|
|
|
|||
|
|
Device:
|
|||
|
|
type: object
|
|||
|
|
properties:
|
|||
|
|
id:
|
|||
|
|
type: integer
|
|||
|
|
format: int64
|
|||
|
|
deviceId:
|
|||
|
|
type: string
|
|||
|
|
ipAddress:
|
|||
|
|
type: string
|
|||
|
|
hostname:
|
|||
|
|
type: string
|
|||
|
|
os:
|
|||
|
|
type: string
|
|||
|
|
currentVersion:
|
|||
|
|
type: string
|
|||
|
|
status:
|
|||
|
|
type: string
|
|||
|
|
enum: [online, offline, upgrading]
|
|||
|
|
groupName:
|
|||
|
|
type: string
|
|||
|
|
lastHeartbeat:
|
|||
|
|
type: string
|
|||
|
|
format: date-time
|
|||
|
|
createdAt:
|
|||
|
|
type: string
|
|||
|
|
format: date-time
|
|||
|
|
updatedAt:
|
|||
|
|
type: string
|
|||
|
|
format: date-time
|
|||
|
|
|
|||
|
|
CheckUpdateResponse:
|
|||
|
|
type: object
|
|||
|
|
properties:
|
|||
|
|
hasUpdate:
|
|||
|
|
type: boolean
|
|||
|
|
description: Whether an update is pending
|
|||
|
|
artefactId:
|
|||
|
|
type: integer
|
|||
|
|
format: int64
|
|||
|
|
description: Artefact ID to pass to the download endpoint
|
|||
|
|
version:
|
|||
|
|
type: string
|
|||
|
|
description: Target version string
|
|||
|
|
fileSize:
|
|||
|
|
type: integer
|
|||
|
|
format: int64
|
|||
|
|
description: Total file size in bytes
|
|||
|
|
sha256Hash:
|
|||
|
|
type: string
|
|||
|
|
description: Expected SHA-256 hex digest (validate after download)
|
|||
|
|
downloadUrl:
|
|||
|
|
type: string
|
|||
|
|
description: Download path relative to the server
|
|||
|
|
|
|||
|
|
StatusResponse:
|
|||
|
|
type: object
|
|||
|
|
properties:
|
|||
|
|
status:
|
|||
|
|
type: string
|
|||
|
|
example: "acknowledged"
|
|||
|
|
|
|||
|
|
ErrorResponse:
|
|||
|
|
type: object
|
|||
|
|
properties:
|
|||
|
|
error:
|
|||
|
|
type: string
|
|||
|
|
description: Human-readable error message
|
|||
|
|
|
|||
|
|
# -- Reusable responses --
|
|||
|
|
responses:
|
|||
|
|
BadRequest:
|
|||
|
|
description: Invalid request body or parameters
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|||
|
|
example:
|
|||
|
|
error: "deviceId is required"
|
|||
|
|
NotFound:
|
|||
|
|
description: Resource not found
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|||
|
|
example:
|
|||
|
|
error: "Artefact not found"
|
|||
|
|
|
|||
|
|
# ─────────────────────────────────────────────────────────────
|
|||
|
|
# Daemon update flow (non-normative)
|
|||
|
|
# ─────────────────────────────────────────────────────────────
|
|||
|
|
x-daemon-flow:
|
|||
|
|
polling:
|
|||
|
|
interval: "5m (configurable)"
|
|||
|
|
description: |
|
|||
|
|
1. **Startup** → `POST /devices/register`
|
|||
|
|
2. **Every N s** → `POST /devices/heartbeat`
|
|||
|
|
3. **Every 5 min** → `GET /devices/check-update?deviceId=xxx`
|
|||
|
|
4. **If hasUpdate==true** →
|
|||
|
|
a. `POST /deployments/{id}/status` → `downloading`
|
|||
|
|
b. `GET /packages/download/{artefactId}?deviceId=xxx&deploymentId={id}`
|
|||
|
|
- Use `Range: bytes=<offset>-` to resume interrupted transfers
|
|||
|
|
c. Verify SHA-256 hash against `sha256Hash` from step 3
|
|||
|
|
d. `POST /deployments/{id}/status` → `verifying`
|
|||
|
|
e. `POST /deployments/{id}/status` → `installing`
|
|||
|
|
f. Restart the Java process, confirm health
|
|||
|
|
g. `POST /deployments/{id}/status` → `completed`
|
|||
|
|
h. `POST /devices/heartbeat` with the new `currentVersion`
|
|||
|
|
- **On any failure** → `POST /deployments/{id}/status` → `failed`
|