mirror of
https://github.com/Telecominfraproject/wlan-cloud-ucentralfms.git
synced 2026-01-04 11:01:41 +00:00
751 lines
19 KiB
YAML
751 lines
19 KiB
YAML
openapi: 3.0.1
|
|
info:
|
|
title: uCentral Firmware Service API
|
|
description: A process to manage new uCentral firmware distribution.
|
|
version: 2.0.0
|
|
license:
|
|
name: BSD3
|
|
url: https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/LICENSE
|
|
contact:
|
|
name: Arilia Support
|
|
url: https://www.ucentral.info/support
|
|
|
|
servers:
|
|
- url: 'https://localhost:16003/api/v1'
|
|
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- bearerAuth: []
|
|
|
|
components:
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: X-API-KEY
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
|
|
responses:
|
|
NotFound:
|
|
description: The specified resource was not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
ErrorCode:
|
|
type: integer
|
|
ErrorDetails:
|
|
type: string
|
|
ErrorDescription:
|
|
type: string
|
|
|
|
Unauthorized:
|
|
description: The requested does not have sufficient rights to perform the operation.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
ErrorCode:
|
|
type: integer
|
|
ErrorDetails:
|
|
type: string
|
|
ErrorDescription:
|
|
type: string
|
|
|
|
Success:
|
|
description: The requested operation was performed.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
Operation:
|
|
type: string
|
|
Details:
|
|
type: string
|
|
Code:
|
|
type: integer
|
|
|
|
schemas:
|
|
FirmwareDetails:
|
|
type: object
|
|
description: Definition of a firmware release
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
deviceType:
|
|
type: string
|
|
description:
|
|
type: string
|
|
revision:
|
|
type: string
|
|
uri:
|
|
type: string
|
|
format: uri
|
|
image:
|
|
type: string
|
|
imageDate:
|
|
type: integer
|
|
format: int64
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
downloadCount:
|
|
type: integer
|
|
format: int64
|
|
firmwareHash:
|
|
type: string
|
|
owner:
|
|
type: string
|
|
location:
|
|
type: string
|
|
format: uri
|
|
uploader:
|
|
type: string
|
|
digest:
|
|
type: string
|
|
latest:
|
|
type: boolean
|
|
notes:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/NoteInfo'
|
|
created:
|
|
type: integer
|
|
format: int64
|
|
|
|
FirmwareDetailsList:
|
|
type: object
|
|
properties:
|
|
firmwares:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/FirmwareDetails'
|
|
|
|
RevisionHistoryEntry:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
serialNumber:
|
|
type: string
|
|
revisionId:
|
|
type: string
|
|
format: uuid
|
|
upgraded:
|
|
type: integer
|
|
format: int64
|
|
fromRelease:
|
|
type: string
|
|
toRelease:
|
|
type: string
|
|
commandUUID:
|
|
type: string
|
|
format: uuid
|
|
|
|
RevisionHistoryEntryList:
|
|
type: object
|
|
properties:
|
|
history:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/RevisionHistoryEntry'
|
|
|
|
|
|
FirmwareAgeDetails:
|
|
type: object
|
|
properties:
|
|
latestId:
|
|
type: string
|
|
image:
|
|
type: string
|
|
imageDate:
|
|
type: integer
|
|
format: uint64
|
|
revision:
|
|
type: string
|
|
uri:
|
|
type: string
|
|
format: uri
|
|
age:
|
|
type: integer
|
|
format: int64
|
|
example: this is in seconds. a 0 means we cannot determine the age. something like 'unknown' should be shown to the user.
|
|
latest:
|
|
type: boolean
|
|
|
|
FirmwareAgeDetailsList:
|
|
type: object
|
|
properties:
|
|
ages:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/FirmwareAgeDetails'
|
|
|
|
DeviceConnectionInformation:
|
|
type: object
|
|
properties:
|
|
serialNumber:
|
|
type: string
|
|
revision:
|
|
type: string
|
|
deviceType:
|
|
type: string
|
|
endPoint:
|
|
type: string
|
|
format: uri
|
|
lastUpdate:
|
|
type: integer
|
|
format: uint64
|
|
status:
|
|
type: string
|
|
enum:
|
|
- connected
|
|
- disconnected
|
|
- unknown
|
|
|
|
DeviceConnectionInformationList:
|
|
type: object
|
|
properties:
|
|
devices:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/DeviceConnectionInformation'
|
|
|
|
DeviceReport:
|
|
type: object
|
|
properties:
|
|
snapshot:
|
|
type: integer
|
|
format: int64
|
|
numberOfDevices:
|
|
type: integer
|
|
format: int64
|
|
ouis:
|
|
$ref: '#/components/schemas/TagIntPairList'
|
|
revisions:
|
|
$ref: '#/components/schemas/TagIntPairList'
|
|
deviceTypes:
|
|
$ref: '#/components/schemas/TagIntPairList'
|
|
status:
|
|
$ref: '#/components/schemas/TagIntPairList'
|
|
endPoints:
|
|
$ref: '#/components/schemas/TagIntPairList'
|
|
unknownFirmwares:
|
|
$ref: '#/components/schemas/TagIntPairList'
|
|
usingLatest:
|
|
$ref: '#/components/schemas/TagIntPairList'
|
|
|
|
#########################################################################################
|
|
##
|
|
## These are endpoints that all services in the uCentral stack must provide
|
|
##
|
|
#########################################################################################
|
|
AnyPayload:
|
|
type: object
|
|
properties:
|
|
Document:
|
|
type: string
|
|
|
|
StringList:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
TagValuePair:
|
|
type: object
|
|
properties:
|
|
tag:
|
|
type: string
|
|
value:
|
|
type: string
|
|
|
|
TagValuePairList:
|
|
type: object
|
|
properties:
|
|
tagList:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TagValuePair'
|
|
|
|
TagIntPair:
|
|
type: object
|
|
properties:
|
|
tag:
|
|
type: string
|
|
value:
|
|
type: integer
|
|
format: int64
|
|
|
|
TagIntPairList:
|
|
type: object
|
|
properties:
|
|
tagList:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TagIntPair'
|
|
|
|
SystemCommandDetails:
|
|
type: object
|
|
properties:
|
|
command:
|
|
type: string
|
|
enum:
|
|
- setloglevels
|
|
- getloglevels
|
|
- getSubSystemNames
|
|
- getLogLevelNames
|
|
- stats
|
|
parameters:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/StringList'
|
|
- $ref: '#/components/schemas/TagValuePairList'
|
|
|
|
SystemCommandResults:
|
|
type: object
|
|
oneOf:
|
|
- $ref: '#/components/schemas/StringList'
|
|
- $ref: '#/components/schemas/TagValuePairList'
|
|
|
|
NoteInfo:
|
|
type: object
|
|
properties:
|
|
created:
|
|
type: integer
|
|
format: int64
|
|
createdBy:
|
|
type: string
|
|
note:
|
|
type: string
|
|
|
|
#########################################################################################
|
|
##
|
|
## End of uCentral system wide values
|
|
##
|
|
#########################################################################################
|
|
|
|
paths:
|
|
/firmwares:
|
|
get:
|
|
tags:
|
|
- Firmware
|
|
summary: Returns a list of firmwares.
|
|
description: Get a list of firmwares.
|
|
operationId: getFirmwareList
|
|
parameters:
|
|
- in: query
|
|
description: Pagination start (starts at 1. If not specified, 1 is assumed)
|
|
name: offset
|
|
schema:
|
|
type: integer
|
|
required: false
|
|
- in: query
|
|
description: Maximum number of entries to return (if absent, no limit is assumed)
|
|
name: limit
|
|
schema:
|
|
type: integer
|
|
required: false
|
|
- in: query
|
|
description: Filter the results
|
|
name: filter
|
|
schema:
|
|
type: string
|
|
required: false
|
|
- in: query
|
|
name: latestOnly
|
|
description: Return only the latest firwares
|
|
schema:
|
|
type: boolean
|
|
required: false
|
|
- in: query
|
|
name: deviceType
|
|
schema:
|
|
type: string
|
|
required: false
|
|
- in: query
|
|
name: revisionSet
|
|
schema:
|
|
type: boolean
|
|
required: false
|
|
- in: query
|
|
name: deviceSet
|
|
schema:
|
|
type: boolean
|
|
required: false
|
|
responses:
|
|
200:
|
|
description: List firmwares
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FirmwareDetailsList'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/firmware/{id}:
|
|
get:
|
|
tags:
|
|
- Firmware
|
|
summary: Returns a Firmware
|
|
description: Get a Firmware.
|
|
operationId: getFirmware
|
|
parameters:
|
|
- in: path
|
|
name: id
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: true
|
|
responses:
|
|
200:
|
|
description: A Firmware definition
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FirmwareDetails'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
post:
|
|
tags:
|
|
- Firmware
|
|
summary: Create A New firmware
|
|
operationId: createFirmware
|
|
parameters:
|
|
- in: path
|
|
name: id
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FirmwareDetails'
|
|
responses:
|
|
200:
|
|
description: Created a firmware entry.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FirmwareDetails'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
put:
|
|
tags:
|
|
- Firmware
|
|
summary: Update A New firmware
|
|
operationId: upodateFirmware
|
|
parameters:
|
|
- in: path
|
|
name: id
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: true
|
|
requestBody:
|
|
description: Firmware details
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FirmwareDetails'
|
|
responses:
|
|
200:
|
|
description: Successfully updated firmware
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FirmwareDetails'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
delete:
|
|
tags:
|
|
- Firmware
|
|
summary: Delete some Firmware
|
|
operationId: deleteFirmware
|
|
parameters:
|
|
- in: path
|
|
name: id
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: true
|
|
responses:
|
|
200:
|
|
description: Successfully deleted Firmware for the device.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/responses/Success'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/revisionHistory/{serialNumber}:
|
|
get:
|
|
tags:
|
|
- RevisionHistory
|
|
summary: List all the defined device revision history
|
|
operationId: getRevisionHistory
|
|
parameters:
|
|
- in: path
|
|
name: serialNumber
|
|
schema:
|
|
type: string
|
|
required: true
|
|
- in: query
|
|
description: Pagination start (starts at 1. If not specified, 1 is assumed)
|
|
name: offset
|
|
schema:
|
|
type: integer
|
|
required: false
|
|
- in: query
|
|
description: Maximum number of entries to return (if absent, no limit is assumed)
|
|
name: limit
|
|
schema:
|
|
type: integer
|
|
required: false
|
|
- in: query
|
|
description: Filter the results
|
|
name: filter
|
|
schema:
|
|
type: string
|
|
required: false
|
|
responses:
|
|
200:
|
|
description: List of device history upgrade.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/RevisionHistoryEntryList'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
delete:
|
|
tags:
|
|
- RevisionHistory
|
|
summary: Delete specific hostory elements for a device
|
|
operationId: deleteRevisionHistory
|
|
parameters:
|
|
- in: path
|
|
name: serialNumber
|
|
schema:
|
|
type: string
|
|
required: true
|
|
- in: query
|
|
description: Pagination start (starts at 1. If not specified, 1 is assumed)
|
|
name: id
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: true
|
|
responses:
|
|
200:
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/responses/Success'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/firmwareAge:
|
|
get:
|
|
tags:
|
|
- Firmware
|
|
summary: Calculate how old a version of firmware is.
|
|
operationId: getFirmwareAge
|
|
parameters:
|
|
- in: query
|
|
description: The exact current verion of the firmware on that device.
|
|
name: revision
|
|
schema:
|
|
type: string
|
|
required: true
|
|
- in: query
|
|
description: The exact current verion of the firmware on that device.
|
|
name: deviceType
|
|
schema:
|
|
type: string
|
|
required: true
|
|
- in: query
|
|
description: Specify lits of serial numbers to retrive age for
|
|
name: select
|
|
schema:
|
|
type: string
|
|
example: select=serial1,serial2,serial4,serial5.
|
|
required: false
|
|
responses:
|
|
200:
|
|
description: The recommended latest version to update to.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/FirmwareAgeDetails'
|
|
- $ref: '#/components/schemas/FirmwareAgeDetailsList'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/connectedDevices:
|
|
get:
|
|
tags:
|
|
- ConnectedDevices
|
|
summary: Get a list of connected devices and some values.
|
|
operationId: getConnectedDevices
|
|
parameters:
|
|
- in: query
|
|
description: Pagination start (starts at 1. If not specified, 1 is assumed)
|
|
name: offset
|
|
schema:
|
|
type: integer
|
|
required: false
|
|
- in: query
|
|
description: Maximum number of entries to return (if absent, no limit is assumed)
|
|
name: limit
|
|
schema:
|
|
type: integer
|
|
required: false
|
|
- in: query
|
|
description: Filter the results
|
|
name: filter
|
|
schema:
|
|
type: string
|
|
required: false
|
|
responses:
|
|
200:
|
|
description: List firmwares
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DeviceConnectionInformationList'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/connectedDevice/{serialNumber}:
|
|
get:
|
|
tags:
|
|
- ConnectedDevices
|
|
summary: Get status of a connected device.
|
|
operationId: getConnectedDevice
|
|
parameters:
|
|
- in: path
|
|
description: SerialNumber of the device
|
|
name: serialNumber
|
|
schema:
|
|
type: string
|
|
required: true
|
|
responses:
|
|
200:
|
|
description: Get information about a connected device.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DeviceConnectionInformation'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/deviceReport:
|
|
get:
|
|
tags:
|
|
- DeviceInfo
|
|
summary: get an analysis of the existing devices we know about.
|
|
responses:
|
|
200:
|
|
description: A full analysis report
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DeviceReport'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
#########################################################################################
|
|
##
|
|
## These are endpoints that all services in the uCentral stack must provide
|
|
##
|
|
#########################################################################################
|
|
/system:
|
|
post:
|
|
tags:
|
|
- System Commands
|
|
summary: Perform some systeme wide commands
|
|
operationId: systemCommand
|
|
requestBody:
|
|
description: Command details
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SystemCommandDetails'
|
|
responses:
|
|
200:
|
|
description: Successfull command execution
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SystemCommandResults'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
get:
|
|
tags:
|
|
- System Commands
|
|
summary: Retrieve different values from the running service.
|
|
operationId: getSystemCommand
|
|
parameters:
|
|
- in: query
|
|
description: Get a value
|
|
name: command
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- version
|
|
- times
|
|
required: true
|
|
|
|
responses:
|
|
200:
|
|
description: Successfull command execution
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TagValuePair'
|
|
403:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|