276 lines
7.6 KiB
YAML
276 lines
7.6 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: SPORE Registry API
|
|
description: |
|
|
RESTful API for managing firmware binaries in the SPORE embedded system.
|
|
|
|
The SPORE registry provides storage and distribution of versioned firmware binaries
|
|
with metadata management and hierarchical file organization.
|
|
|
|
## Features
|
|
- **Firmware Upload**: Store firmware binaries with metadata
|
|
- **Firmware Listing**: Query firmware by name, version, or labels
|
|
- **Firmware Download**: Retrieve specific firmware versions
|
|
- **Version Management**: Semantic versioning support with hierarchical storage
|
|
|
|
## Storage Structure
|
|
Firmware binaries are stored hierarchically as:
|
|
```
|
|
registry/{name}/{version}/firmware.bin
|
|
```
|
|
|
|
Metadata is stored in SQLite database with labels for flexible querying.
|
|
version: 1.0.0
|
|
contact:
|
|
name: SPORE Development Team
|
|
url: https://git.dcentral.systems/iot/spore
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
|
|
servers:
|
|
- url: http://localhost:8080
|
|
description: Local SPORE registry server
|
|
|
|
paths:
|
|
/firmware:
|
|
post:
|
|
summary: Upload firmware binary
|
|
description: |
|
|
Upload a firmware binary with metadata. The firmware is stored in the
|
|
hierarchical file structure and metadata is saved to the database.
|
|
operationId: uploadFirmware
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- metadata
|
|
- firmware
|
|
properties:
|
|
metadata:
|
|
type: string
|
|
description: JSON metadata for the firmware
|
|
example: |
|
|
{
|
|
"name": "base",
|
|
"version": "1.0.0",
|
|
"labels": {
|
|
"app": "base",
|
|
"platform": "esp32"
|
|
}
|
|
}
|
|
firmware:
|
|
type: string
|
|
format: binary
|
|
description: Firmware binary file
|
|
responses:
|
|
'201':
|
|
description: Firmware uploaded successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
name:
|
|
type: string
|
|
example: "base"
|
|
version:
|
|
type: string
|
|
example: "1.0.0"
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
example: 245760
|
|
'400':
|
|
description: Bad request - missing or invalid parameters
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
|
|
get:
|
|
summary: List firmware records
|
|
description: |
|
|
Retrieve firmware records with optional filtering by name, version, or labels.
|
|
Returns metadata for each firmware including download URLs.
|
|
operationId: listFirmware
|
|
parameters:
|
|
- name: name
|
|
in: query
|
|
description: Filter by firmware name
|
|
required: false
|
|
schema:
|
|
type: string
|
|
example: "base"
|
|
- name: version
|
|
in: query
|
|
description: Filter by firmware version
|
|
required: false
|
|
schema:
|
|
type: string
|
|
example: "1.0.0"
|
|
responses:
|
|
'200':
|
|
description: List of firmware records
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: "base"
|
|
version:
|
|
type: string
|
|
example: "1.0.0"
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
example: 245760
|
|
labels:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
example:
|
|
app: "base"
|
|
platform: "esp32"
|
|
download_url:
|
|
type: string
|
|
example: "/firmware/base/1.0.0"
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
|
|
/firmware/{name}/{version}:
|
|
get:
|
|
summary: Download firmware binary
|
|
description: |
|
|
Download the firmware binary for the specified name and version.
|
|
Returns the binary file directly.
|
|
operationId: downloadFirmware
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: Firmware name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: "base"
|
|
- name: version
|
|
in: path
|
|
description: Firmware version (semantic versioning)
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: "1.0.0"
|
|
responses:
|
|
'200':
|
|
description: Firmware binary file
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'404':
|
|
description: Firmware not found
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
|
|
/health:
|
|
get:
|
|
summary: Health check
|
|
description: Simple health check endpoint
|
|
operationId: healthCheck
|
|
responses:
|
|
'200':
|
|
description: Service is healthy
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
example: "healthy"
|
|
|
|
components:
|
|
schemas:
|
|
FirmwareMetadata:
|
|
type: object
|
|
required:
|
|
- name
|
|
- version
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Firmware name
|
|
example: "base"
|
|
version:
|
|
type: string
|
|
description: Firmware version (semantic versioning)
|
|
example: "1.0.0"
|
|
labels:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: Key-value labels for categorizing firmware
|
|
example:
|
|
app: "base"
|
|
platform: "esp32"
|
|
|
|
FirmwareRecord:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: "base"
|
|
version:
|
|
type: string
|
|
example: "1.0.0"
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
example: 245760
|
|
labels:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
download_url:
|
|
type: string
|
|
example: "/firmware/base/1.0.0"
|
|
|
|
Error:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
description: Error message
|
|
code:
|
|
type: integer
|
|
description: HTTP status code
|