feat: basic firmware registry
This commit is contained in:
275
api/openapi.yaml
Normal file
275
api/openapi.yaml
Normal file
@@ -0,0 +1,275 @@
|
||||
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
|
||||
Reference in New Issue
Block a user