swagger: '2.0'
info:
description: ' vf-OS Device Drivers API.'
version: 0.0.1
title: vf-OS Device Drivers
termsOfService: 'http://swagger.io/terms/'
contact:
email: vf-os-wp2@vf-os.eu
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: vf-os.eu
basePath: /api/drivers/v1
tags:
- name: device
description: a virtual device
externalDocs:
description: Find out more about drivers
url: 'http://vf-os.eu'
- name: sensor
description: A virtual sensor
externalDocs:
description: Find out more about sensors
url: 'http://vf-os.eu'
- name: log
description: log to be sent to the platform
externalDocs:
description: Find out more about sensors
url: 'http://vf-os.eu'
- name: driver
description: driver
externalDocs:
description: Find out more about sensors
url: 'http://vf-os.eu'
- name: metada
description: metadata of the drivers component
externalDocs:
description: Find out more about sensors
url: 'http://vf-os.eu'
schemes:
- http
- https
paths:
/devices:
post:
tags:
- device
summary: Add a new device to the store
description: ''
operationId: addDevice
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: devicedata
description: device object that needs to be added to the store
required: true
schema:
$ref: '#/definitions/deviceConfiguration'
responses:
'200':
description: id of the device created
schema:
type: string
'405':
description: Invalid input
security:
- devicestore_auth:
- 'write:devices'
- 'read:devices'
get:
tags:
- device
summary: list existing registered devices
description: ''
operationId: listDevices
produces:
- application/json
responses:
'200':
description: id of the device created
schema:
type: array
items:
$ref: '#/definitions/deviceConfiguration'
security:
- devicestore_auth:
- 'write:devices'
- 'read:devices'
'/devices/{deviceId}':
put:
tags:
- device
summary: Update an existing device
description: ''
operationId: updateDevice
consumes:
- application/json
produces:
- application/json
parameters:
- in: path
name: deviceId
description: device id of the device that you want to update
required: true
type: string
- in: body
name: devicedata
description: device object that will update existing one
required: true
schema:
$ref: '#/definitions/deviceConfiguration'
responses:
'200':
description: update successfully done
'400':
description: Invalid ID supplied
'404':
description: Device not found
'405':
description: Validation exception
security:
- devicestore_auth:
- 'write:devices'
- 'read:devices'
get:
tags:
- device
summary: Find device by ID
description: Returns a single device
operationId: getDeviceById
produces:
- application/json
parameters:
- name: deviceId
in: path
description: ID of device to return
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/deviceConfiguration'
'400':
description: Invalid ID supplied
'404':
description: device not found
security:
- api_key: []
delete:
tags:
- device
summary: Delete a device by ID
description: Deletes a device
operationId: deleteDevice
produces:
- application/json
parameters:
- name: deviceId
in: path
description: ID of device to return
required: true
type: string
responses:
'200':
description: successful operation
'400':
description: Invalid ID supplied
'404':
description: device not found
security:
- api_key: []
'/devices/{deviceId}/status':
get:
tags:
- device
summary: Get Status of a given device
description: Returns status of the device
operationId: getDeviceStatus
produces:
- application/json
parameters:
- name: deviceId
in: path
description: ID of device
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/deviceStatus'
'400':
description: Invalid ID supplied
'404':
description: device not found
security:
- api_key: []
'/devices/{deviceId}/sensors':
get:
tags:
- device
summary: list sensors of a given device
description: list sensors of a given device
operationId: getDeviceSensors
produces:
- application/json
parameters:
- name: deviceId
in: path
description: ID of device
required: true
type: string
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/sensorData'
'400':
description: Invalid ID supplied
'404':
description: device not found
security:
- api_key: []
post:
tags:
- sensor
summary: register a sensor of a given device
description: register a sensor of a given device
operationId: addSensorToDevice
consumes:
- appplication/json
produces:
- application/json
parameters:
- name: deviceId
in: path
description: ID of device
required: true
type: string
- name: sensorData
in: body
description: data of the sensor
required: true
schema:
$ref: '#/definitions/sensorDetail'
responses:
'200':
description: successful operation
'400':
description: Invalid ID supplied
'404':
description: device not found
security:
- api_key: []
'/devices/{deviceId}/sensors/{sensorId}/Data':
post:
tags:
- sensor
summary: Store proprietary data from Device or Gateway
description: Store proprietary data from Device or Gateway
operationId: storeSensorData
consumes:
- appplication/json
parameters:
- name: deviceId
in: path
description: ID of device
required: true
type: string
- name: sensorId
in: path
description: ID of sensor
required: true
type: string
- name: dataMeasure
in: body
description: data from the sensor
required: true
schema:
$ref: '#/definitions/dataMeasure'
responses:
'200':
description: successful operation
'400':
description: Invalid ID supplied
'404':
description: device not found
security:
- api_key: []
get:
tags:
- sensor
summary: Get data from device / sensor
description: Get data from device / sensor
operationId: getDataSensor
produces:
- application/json
parameters:
- name: deviceId
in: path
description: ID of device
required: true
type: string
- name: sensorId
in: path
description: ID of sensor
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/dataMeasure'
'400':
description: Invalid ID supplied
'404':
description: device not found
security:
- api_key: []
'/devices/{deviceId}/sensors/{sensorId}/Command':
post:
tags:
- sensor
summary: Send Command to Device / Sensor
description: Send Command to Device / Sensor
operationId: sendCommand
consumes:
- appplication/json
parameters:
- name: deviceId
in: path
description: ID of device
required: true
type: string
- name: sensorId
in: path
description: ID of sensor
required: true
type: string
- name: command
in: body
description: command sent to the sensor
required: true
schema:
$ref: '#/definitions/commandOrder'
responses:
'200':
description: successful operation
'400':
description: Invalid ID supplied
'404':
description: device not found
security:
- api_key: []
'/devices/{deviceId}/sensors/{sensorId}/Data/HistoricData':
get:
tags:
- sensor
summary: Get historic data from device / sensor
description: Get historic data from device / sensor
operationId: getHistoricDataSensor
produces:
- application/json
parameters:
- name: deviceId
in: path
description: ID of device
required: true
type: string
- name: sensorId
in: path
description: ID of sensor
required: true
type: string
- name: offset
in: query
description: number of minutes
required: true
type: string
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/dataMeasure'
'400':
description: Invalid ID supplied
'404':
description: device not found
security:
- api_key: []
/logs:
post:
tags:
- log
summary: Log listing (Subscribe)
description: Log listing (Subscribe)
operationId: logSubscribe
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: subscriptionData
description: device object to subscribe the platform to the log
required: true
schema:
$ref: '#/definitions/subscriptionData'
responses:
'200':
description: id of the device created
schema:
$ref: '#/definitions/referenceResult'
'405':
description: Invalid input
security:
- devicestore_auth:
- 'write:devices'
- 'read:devices'
'/logs/{reference}':
delete:
tags:
- log
summary: Log UnSubscribe
description: Log UnSubscribe
operationId: logUnsubscribe
produces:
- application/json
parameters:
- name: reference
in: path
description: reference to unsubscribe a component as listener of logs
required: true
type: string
responses:
'200':
description: successful operation
'400':
description: Invalid ID supplied
'404':
description: device not found
security:
- api_key: []
'/drivers/{driverId}/manifest':
get:
tags:
- driver
summary: Function to retrieve the file manifest of the Drivers component
description: Function to retrieve the file manifest of the Drivers component
operationId: getManifest
produces:
- application/json
parameters:
- in: path
name: driverId
description: Driver ID
required: true
type: string
responses:
'200':
description: manifest
schema:
$ref: '#/definitions/manifestDoc'
'405':
description: Invalid input
security:
- devicestore_auth:
- 'write:devices'
- 'read:devices'
/metadata:
get:
tags:
- metadata
summary: >-
Method to return the endpoint available by the Driver components (REST
verbs). Useful for vf-Platform.
description: >-
Method to return the endpoint available by the Driver components (REST
verbs). Useful for vf-Platform.
operationId: getMetadata
produces:
- application/json
responses:
'200':
description: manifest
schema:
type: array
items:
$ref: '#/definitions/metadataItem'
'405':
description: Invalid input
security:
- devicestore_auth:
- 'write:devices'
- 'read:devices'
securityDefinitions:
devicestore_auth:
type: oauth2
authorizationUrl: 'http://devicestore.swagger.io/oauth/dialog'
flow: implicit
scopes:
'write:devices': modify devices in your account
'read:devices': read your devices
api_key:
type: apiKey
name: api_key
in: header
definitions:
deviceConfiguration:
type: object
required:
- name
- processingExpression
- needProcessing
properties:
_did:
type: string
name:
type: string
example: TS machine
needProcessing:
type: boolean
default: true
processingExpression:
type: string
default: v
propietaryParameters:
type: array
items:
$ref: '#/definitions/proprietaryParam'
proprietaryParam:
type: object
properties:
name:
type: string
value:
type: string
deviceStatus:
type: object
properties:
_did:
type: string
status:
type: array
items:
type: string
enum:
- ok
- failure
- unknown
sensorData:
type: object
properties:
_sid:
type: string
name:
type: string
triggers:
type: array
items:
type: string
historicData:
type: boolean
default: true
actuator:
type: boolean
default: false
status:
type: string
sensorDetail:
type: object
required:
- name
- type
- unit
- triggers
- historicData
- computingExpression
- actuator
properties:
_sid:
type: string
name:
type: string
properties:
type: array
items:
$ref: '#/definitions/property'
type:
type: string
unit:
type: string
triggers:
type: array
items:
$ref: '#/definitions/trigger'
historicData:
type: boolean
default: false
computingExpression:
type: string
default: v
actuator:
type: boolean
propietaryParameters:
type: array
items:
$ref: '#/definitions/proprietaryParam'
property:
type: object
properties:
name:
type: string
value:
type: string
trigger:
type: object
properties:
type:
type: string
triggerConfig:
type: string
dataMeasure:
type: object
properties:
data:
type: number
unit:
type: string
timestamp:
type: string
commandOrder:
type: object
properties:
commandType:
type: string
command:
type: string
subscriptionData:
type: object
properties:
offset:
type: integer
description: 'refresh period to '
callback:
type: string
description: URL endpoint to a REST service to send changes of the logs
referenceResult:
type: object
properties:
reference:
type: string
manifestDoc:
type: object
properties:
manifest:
type: string
example: <driver> xxxxx </driver>
metadataItem:
type: object
properties:
url:
type: string
description: endpoint
desc:
type: string
description: what this endpoint is used for
verb:
type: string
description: type of endpoint
enum:
- POST
- GET
- PUT
- DELETE
externalDocs:
description: Find out more about Swagger
url: 'http://swagger.io'