1041 lines
37 KiB
YAML
1041 lines
37 KiB
YAML
|
openapi: 3.0.0
|
||
|
|
info:
|
||
|
|
title: EdgeX Foundry - Device Service API
|
||
|
|
description: This is the definition of the API for Device services in the EdgeX Foundry IOT microservice platform. Device Services are responsible for obtaining Readings from target devices, and for writing values (settings) to them.
|
||
|
|
version: 4.0.0
|
||
|
|
|
||
|
|
servers:
|
||
|
|
- url: http://0:49999/api/v3
|
||
|
|
description: URL for local development and testing
|
||
|
|
|
||
|
|
components:
|
||
|
|
schemas:
|
||
|
|
AutoEvent:
|
||
|
|
description: "Identifies a resource which will be read automatically by the device service."
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
interval:
|
||
|
|
description: "Specifies a time interval between reading requests. This may be in a combination of hours, minutes, seconds and milliseconds (h/m/s/ms)"
|
||
|
|
type: string
|
||
|
|
example: "1m30s"
|
||
|
|
onChange:
|
||
|
|
description: "If true, new Events will only be generated if successive readings differ in value."
|
||
|
|
type: boolean
|
||
|
|
sourceName:
|
||
|
|
description: "SourceName indicates the name of the resource or device command in the device profile which describes the event to generate"
|
||
|
|
type: string
|
||
|
|
required:
|
||
|
|
- sourceName
|
||
|
|
- frequency
|
||
|
|
BaseRequest:
|
||
|
|
description: "Defines basic properties which all use-case specific request DTO instances should support."
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
requestId:
|
||
|
|
description: "Uniquely identifies this request. For implementation, recommend this value be generated by the type's constructor."
|
||
|
|
type: string
|
||
|
|
format: uuid
|
||
|
|
example: "e6e8a2f4-eb14-4649-9e2b-175247911369"
|
||
|
|
apiVersion:
|
||
|
|
description: "A version number shows the API version in DTOs."
|
||
|
|
type: string
|
||
|
|
example: "v3"
|
||
|
|
required:
|
||
|
|
- apiVersion
|
||
|
|
BaseResponse:
|
||
|
|
description: "Defines basic properties which all use-case specific response DTO instances should support"
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
apiVersion:
|
||
|
|
description: "A version number shows the API version in DTOs."
|
||
|
|
type: string
|
||
|
|
example: "v3"
|
||
|
|
requestId:
|
||
|
|
description: "Uniquely identifies the request that resulted in this response."
|
||
|
|
type: string
|
||
|
|
format: uuid
|
||
|
|
example: "e6e8a2f4-eb14-4649-9e2b-175247911369"
|
||
|
|
statusCode:
|
||
|
|
description: "A numeric code signifying the operational status of the response."
|
||
|
|
type: integer
|
||
|
|
message:
|
||
|
|
description: "A field that can contain a free-form message, such as an error message."
|
||
|
|
type: string
|
||
|
|
Device:
|
||
|
|
description: "A device is an IoT object represented in EdgeX."
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
id:
|
||
|
|
type: string
|
||
|
|
format: uuid
|
||
|
|
description: "The unique identifier of the device"
|
||
|
|
name:
|
||
|
|
type: string
|
||
|
|
description: "The name of the device"
|
||
|
|
description:
|
||
|
|
type: string
|
||
|
|
description: "A free-format descriptive field for additional device information"
|
||
|
|
adminState:
|
||
|
|
type: string
|
||
|
|
enum: [LOCKED, UNLOCKED]
|
||
|
|
description: "Administrative state of the device, allowing it to be locked for policy reasons"
|
||
|
|
operatingState:
|
||
|
|
type: string
|
||
|
|
enum: [UP, DOWN, UNKNOWN]
|
||
|
|
description: "Operating state of the device, indicating whether it is currently responsive"
|
||
|
|
labels:
|
||
|
|
type: array
|
||
|
|
items:
|
||
|
|
type: string
|
||
|
|
description: "Other labels applied to the device to help with searching"
|
||
|
|
location:
|
||
|
|
type: object
|
||
|
|
description: "Device service specific location information"
|
||
|
|
serviceName:
|
||
|
|
type: string
|
||
|
|
description: "Associated device service referenced by name"
|
||
|
|
profileName:
|
||
|
|
type: string
|
||
|
|
description: "Associated device profile referenced by name"
|
||
|
|
autoEvents:
|
||
|
|
type: array
|
||
|
|
items:
|
||
|
|
$ref: '#/components/schemas/AutoEvent'
|
||
|
|
description: "Events which the service should generate automatically from this device."
|
||
|
|
protocols:
|
||
|
|
type: object
|
||
|
|
additionalProperties:
|
||
|
|
$ref: '#/components/schemas/ProtocolProperties'
|
||
|
|
tags:
|
||
|
|
type: object
|
||
|
|
description: "A map of tags used to tag the given device."
|
||
|
|
properties:
|
||
|
|
type: object
|
||
|
|
description: "A map of properties required to address the given device."
|
||
|
|
BaseReading:
|
||
|
|
description: "A base reading type containing common properties from which more specific reading types inherit. This definition should not be implemented but is used elsewhere to indicate support for a mixed list of simple/binary readings in a single event."
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
apiVersion:
|
||
|
|
description: "A version number shows the API version in DTOs."
|
||
|
|
type: string
|
||
|
|
id:
|
||
|
|
description: "The unique identifier for the reading"
|
||
|
|
type: string
|
||
|
|
format: uuid
|
||
|
|
created:
|
||
|
|
description: "A Unix timestamp indicating when (if) the reading was initially persisted to a database."
|
||
|
|
type: integer
|
||
|
|
origin:
|
||
|
|
description: "A Unix timestamp indicating when the reading was originated at the source device (can support nanoseconds)"
|
||
|
|
type: integer
|
||
|
|
deviceName:
|
||
|
|
description: "The name of the device from which the reading originated"
|
||
|
|
type: string
|
||
|
|
resourceName:
|
||
|
|
description: "The device resource name for the reading"
|
||
|
|
type: string
|
||
|
|
profileName:
|
||
|
|
description: "The device profile name for the reading"
|
||
|
|
type: string
|
||
|
|
valueType:
|
||
|
|
description: "Indicates the datatype of the value property"
|
||
|
|
type: string
|
||
|
|
required:
|
||
|
|
- deviceName
|
||
|
|
- resourceName
|
||
|
|
- profileName
|
||
|
|
- origin
|
||
|
|
- valueType
|
||
|
|
SimpleReading:
|
||
|
|
description: "An event reading for a simple data type"
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/BaseReading'
|
||
|
|
- type: object
|
||
|
|
properties:
|
||
|
|
value:
|
||
|
|
description: "A string representation of the reading's value"
|
||
|
|
type: string
|
||
|
|
required:
|
||
|
|
- value
|
||
|
|
BinaryReading:
|
||
|
|
description: "An event reading for a binary data type"
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/BaseReading'
|
||
|
|
- type: object
|
||
|
|
properties:
|
||
|
|
binaryValue:
|
||
|
|
description: "If the value of the reading is binary, it will be found in this property as a byte array"
|
||
|
|
type: string
|
||
|
|
format: byte
|
||
|
|
mediaType:
|
||
|
|
description: "E.g. MIME Type, indicates what the content type of the binaryValue property is if it's populated."
|
||
|
|
type: string
|
||
|
|
required:
|
||
|
|
- binaryValue
|
||
|
|
- mediaType
|
||
|
|
Event:
|
||
|
|
description: "A discrete event containing one or more readings"
|
||
|
|
properties:
|
||
|
|
apiVersion:
|
||
|
|
description: "A version number shows the API version in DTOs."
|
||
|
|
type: string
|
||
|
|
id:
|
||
|
|
description: "The unique identifier for the event"
|
||
|
|
type: string
|
||
|
|
format: uuid
|
||
|
|
deviceName:
|
||
|
|
description: "The name of the device from which the event originated"
|
||
|
|
type: string
|
||
|
|
profileName:
|
||
|
|
description: "The name of the device profile from which the event originated"
|
||
|
|
type: string
|
||
|
|
created:
|
||
|
|
description: "A Unix timestamp indicating when (if) the event was initially persisted to a database."
|
||
|
|
type: integer
|
||
|
|
origin:
|
||
|
|
description: "A Unix timestamp indicating when the event was originated at the source device (can support nanoseconds)"
|
||
|
|
type: integer
|
||
|
|
readings:
|
||
|
|
description: "One or more readings captured at the time of the event"
|
||
|
|
type: array
|
||
|
|
items:
|
||
|
|
oneOf:
|
||
|
|
- $ref: '#/components/schemas/SimpleReading'
|
||
|
|
- $ref: '#/components/schemas/BinaryReading'
|
||
|
|
tags:
|
||
|
|
description: "List of zero or more Tags attached to the Event which give more context to the Event"
|
||
|
|
title: tags
|
||
|
|
type: object
|
||
|
|
example:
|
||
|
|
Gateway-id: "HoustonStore-000123"
|
||
|
|
Latitude: "29.630771"
|
||
|
|
Longitude: "-95.377603"
|
||
|
|
required:
|
||
|
|
- id
|
||
|
|
- deviceName
|
||
|
|
- profileName
|
||
|
|
- origin
|
||
|
|
- readings
|
||
|
|
EventResponse:
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/BaseResponse'
|
||
|
|
description: "A response type for returning an Event to the caller."
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
event:
|
||
|
|
$ref: '#/components/schemas/Event'
|
||
|
|
ErrorResponse:
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/BaseResponse'
|
||
|
|
description: "A response type for returning a generic error to the caller."
|
||
|
|
type: object
|
||
|
|
ConfigResponse:
|
||
|
|
description: "Provides a response containing the configuration for the targeted service."
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
apiVersion:
|
||
|
|
description: "A version number shows the API version in DTOs."
|
||
|
|
type: string
|
||
|
|
serviceName:
|
||
|
|
description: "Outputs the name of the service the response is from"
|
||
|
|
type: string
|
||
|
|
config:
|
||
|
|
description: "An object containing the service''s configuration. Please refer to Core Data''s configuration documentation for more details at [EdgeX Foundry Documentation](https://docs.edgexfoundry.org)."
|
||
|
|
type: object
|
||
|
|
DeviceValidationRequest:
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/BaseRequest'
|
||
|
|
description: "Notification that a new device associated with this device service has been created."
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
device:
|
||
|
|
$ref: '#/components/schemas/Device'
|
||
|
|
required:
|
||
|
|
- device
|
||
|
|
PingResponse:
|
||
|
|
description: "A response from the /ping endpoint indicating that the service is functioning."
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
apiVersion:
|
||
|
|
description: "A version number shows the API version in DTOs."
|
||
|
|
type: string
|
||
|
|
timestamp:
|
||
|
|
description: "Outputs the current server timestamp in RFC1123 format"
|
||
|
|
example: "Mon, 02 Jan 2006 15:04:05 MST"
|
||
|
|
type: string
|
||
|
|
serviceName:
|
||
|
|
description: "Outputs the name of the service the response is from"
|
||
|
|
type: string
|
||
|
|
ProtocolProperties:
|
||
|
|
description: "The properties required to address a device via a particular protocol."
|
||
|
|
example: {"Host":"floor4.hq.acme.com", "Port":"8080"}
|
||
|
|
type: object
|
||
|
|
additionalProperties:
|
||
|
|
type: string
|
||
|
|
SecretRequest:
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/BaseRequest'
|
||
|
|
description: Defines the secret data to be stored
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
secretName:
|
||
|
|
description: Specifies the name of the secret
|
||
|
|
type: string
|
||
|
|
example: "credentials"
|
||
|
|
secretData:
|
||
|
|
description: A list of the key/value pairs of secret data to store
|
||
|
|
type: array
|
||
|
|
items:
|
||
|
|
$ref: '#/components/schemas/SecretDataKeyValue'
|
||
|
|
required:
|
||
|
|
- secretName
|
||
|
|
- secretData
|
||
|
|
SecretDataKeyValue:
|
||
|
|
description: Defines a key/value pair of the secret data
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
key:
|
||
|
|
description: The key to identify the secret
|
||
|
|
type: string
|
||
|
|
example: "username"
|
||
|
|
value:
|
||
|
|
description: The value of the secret
|
||
|
|
type: string
|
||
|
|
example: "mqtt-user"
|
||
|
|
required:
|
||
|
|
- key
|
||
|
|
- value
|
||
|
|
SettingRequest:
|
||
|
|
description: "Defines new values to be written to device resources, as part of an actuation (put) command to a device"
|
||
|
|
additionalProperties:
|
||
|
|
type: string
|
||
|
|
title: Setting
|
||
|
|
type: object
|
||
|
|
example: {"AHU-TargetTemperature": "28.5", "AHU-TargetBand": "4.0"}
|
||
|
|
VersionResponse:
|
||
|
|
description: "A response returned from the /version endpoint whose purpose is to report out the latest version supported by the service."
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
apiVersion:
|
||
|
|
description: "A version number shows the API version in DTOs."
|
||
|
|
type: string
|
||
|
|
version:
|
||
|
|
description: "The latest version supported by the service."
|
||
|
|
type: string
|
||
|
|
sdk_version:
|
||
|
|
description: "The version of the SDK with which the service was built."
|
||
|
|
type: string
|
||
|
|
serviceName:
|
||
|
|
description: "Outputs the name of the service the response is from"
|
||
|
|
type: string
|
||
|
|
ProfileScanRequest:
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/BaseRequest'
|
||
|
|
description: Defines the information for the profile scan
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
deviceName:
|
||
|
|
description: Specifies the device to generate the profile
|
||
|
|
type: string
|
||
|
|
example: "Test-Device"
|
||
|
|
profileName:
|
||
|
|
description: Specifies the unique profile name. Default format is {deviceName}_profile_{timestamp}
|
||
|
|
type: string
|
||
|
|
example: "Test-Device_profile_1720169510"
|
||
|
|
options:
|
||
|
|
type: object
|
||
|
|
example:
|
||
|
|
DiscoverMode: "All"
|
||
|
|
DiscoverProperties: [ 103, 117 ]
|
||
|
|
DiscoverObjects: [ 1, 2, 3, 4, 5]
|
||
|
|
required:
|
||
|
|
- deviceName
|
||
|
|
|
||
|
|
parameters:
|
||
|
|
correlatedRequestHeader:
|
||
|
|
in: header
|
||
|
|
name: X-Correlation-ID
|
||
|
|
description: "A unique identifier correlating a request to its associated response, facilitating tracing through being included on requests originating from the initiating request."
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
format: uuid
|
||
|
|
example: "14a42ea6-c394-41c3-8bcd-a29b9f5e6835"
|
||
|
|
|
||
|
|
headers:
|
||
|
|
correlatedResponseHeader:
|
||
|
|
description: "A response header that returns the unique correlation ID used to initiate the request."
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
format: uuid
|
||
|
|
required: true
|
||
|
|
example: "14a42ea6-c394-41c3-8bcd-a29b9f5e6835"
|
||
|
|
|
||
|
|
examples:
|
||
|
|
400Example:
|
||
|
|
value:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "4c57bd0b-1cee-4056-8a8a-98eea8d999c6"
|
||
|
|
statusCode: 400
|
||
|
|
message: "Bad Request"
|
||
|
|
404Example:
|
||
|
|
value:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "afe9a1f4-bc45-434c-6eb2-105440912368"
|
||
|
|
statusCode: 404
|
||
|
|
message: "Not Found"
|
||
|
|
405Example:
|
||
|
|
value:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "e6e8a2f9-eb14-4649-9e2b-175247911369"
|
||
|
|
statusCode: 405
|
||
|
|
message: "Method Not Allowed"
|
||
|
|
423Example:
|
||
|
|
value:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "8a41b3f4-0148-11eb-adc1-0242ac120002"
|
||
|
|
statusCode: 423
|
||
|
|
message: "Locked"
|
||
|
|
500Example:
|
||
|
|
value:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "cd319159-928c-4a6f-9d3d-a821c524ac35"
|
||
|
|
statusCode: 500
|
||
|
|
message: "Internal Server Error"
|
||
|
|
|
||
|
|
paths:
|
||
|
|
/device/name/{name}/{command}:
|
||
|
|
get:
|
||
|
|
description: Request the device/sensor by its name to return the current (or in some cases new) event/reading values for the command or device resource specified. The device service may have cached the latest event/reading for the sensor(s) or it may immediate request new event/reading values depending on the implementation and the device(s)/sensor(s) capability.
|
||
|
|
parameters:
|
||
|
|
- $ref: '#/components/parameters/correlatedRequestHeader'
|
||
|
|
- in: path
|
||
|
|
name: name
|
||
|
|
required: true
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
example: sensor01
|
||
|
|
description: "A name uniquely identifying a device."
|
||
|
|
- in: path
|
||
|
|
name: command
|
||
|
|
required: true
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
example: command01
|
||
|
|
description: "A name uniquely identifying a command."
|
||
|
|
- in: query
|
||
|
|
name: ds-pushevent
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
enum:
|
||
|
|
- true
|
||
|
|
- false
|
||
|
|
default: false
|
||
|
|
example: true
|
||
|
|
description: "If set to true, a successful GET will result in an event being pushed to the EdgeX system"
|
||
|
|
- in: query
|
||
|
|
name: ds-returnevent
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
enum:
|
||
|
|
- true
|
||
|
|
- false
|
||
|
|
default: true
|
||
|
|
example: false
|
||
|
|
description: "If set to false, there will be no Event returned in the http response"
|
||
|
|
- in: query
|
||
|
|
name: ds-regexcmd
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
enum:
|
||
|
|
- true
|
||
|
|
- false
|
||
|
|
default: true
|
||
|
|
example: false
|
||
|
|
description: "If set to false, the command name will be treated as normal string instead of regex syntax"
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: String as returned by the device/sensor through the device service.
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
'application/json':
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/EventResponse'
|
||
|
|
'404':
|
||
|
|
description: If no device exists by the name provided or the command is unknown.
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
404Example:
|
||
|
|
$ref: '#/components/examples/404Example'
|
||
|
|
'405':
|
||
|
|
description: If the requested command exists but not for GET, or the resource is marked as write-only.
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
405Example:
|
||
|
|
$ref: '#/components/examples/405Example'
|
||
|
|
'423':
|
||
|
|
description: If the device or service is locked (admin state), disabled (operating state), or lacks associated profile.
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
423Example:
|
||
|
|
$ref: '#/components/examples/423Example'
|
||
|
|
'500':
|
||
|
|
description: The device driver is unable to process the request, or too many values were returned.
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
500Example:
|
||
|
|
$ref: '#/components/examples/500Example'
|
||
|
|
put:
|
||
|
|
description: Request the actuator by its name to trigger a action or set a current value for the command or device resource specified.
|
||
|
|
parameters:
|
||
|
|
- $ref: '#/components/parameters/correlatedRequestHeader'
|
||
|
|
- in: path
|
||
|
|
name: name
|
||
|
|
required: true
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
example: sensor
|
||
|
|
- in: path
|
||
|
|
name: command
|
||
|
|
required: true
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
example: allValues
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: The PUT command was successful.
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "48395596-9f75-4556-97b4-8a834d26c1c7"
|
||
|
|
statusCode: 200
|
||
|
|
'404':
|
||
|
|
description: If no device exists for the name provided or the command is unknown.
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
404Example:
|
||
|
|
$ref: '#/components/examples/404Example'
|
||
|
|
'405':
|
||
|
|
description: If the requested command exists but not for PUT, or the resource is marked as read-only.
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
405Example:
|
||
|
|
$ref: '#/components/examples/405Example'
|
||
|
|
'423':
|
||
|
|
description: If the device or service is locked (admin state) or disabled (operating state).
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
423Example:
|
||
|
|
$ref: '#/components/examples/423Example'
|
||
|
|
'500':
|
||
|
|
description: The device driver is unable to process the request.
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
500Example:
|
||
|
|
$ref: '#/components/examples/500Example'
|
||
|
|
requestBody:
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/SettingRequest'
|
||
|
|
required: true
|
||
|
|
|
||
|
|
/secret:
|
||
|
|
parameters:
|
||
|
|
- $ref: '#/components/parameters/correlatedRequestHeader'
|
||
|
|
post:
|
||
|
|
summary: Stores a secret to the secure Secret Store
|
||
|
|
requestBody:
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/SecretRequest'
|
||
|
|
required: true
|
||
|
|
responses:
|
||
|
|
'201':
|
||
|
|
description: "Created"
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "9dab3997-b399-4630-972c-d4ffa571f1f2"
|
||
|
|
statusCode: 201
|
||
|
|
'400':
|
||
|
|
description: "Invalid request."
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
400Example:
|
||
|
|
$ref: '#/components/examples/400Example'
|
||
|
|
'500':
|
||
|
|
description: "An unexpected error happened on the server."
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
500Example:
|
||
|
|
$ref: '#/components/examples/500Example'
|
||
|
|
|
||
|
|
/discovery:
|
||
|
|
post:
|
||
|
|
description: Run the discovery request for a Device Service. No request body is required.
|
||
|
|
responses:
|
||
|
|
'202':
|
||
|
|
description: The service is running the discovery request.
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
|
||
|
|
statusCode: 202
|
||
|
|
message: "Device Discovery is triggered"
|
||
|
|
'423':
|
||
|
|
description: The service is disabled or administratively locked.
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
423Example:
|
||
|
|
$ref: '#/components/examples/423Example'
|
||
|
|
'500':
|
||
|
|
description: An unexpected error occurred on the server
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
500Example:
|
||
|
|
$ref: '#/components/examples/500Example'
|
||
|
|
'503':
|
||
|
|
description: Discovery is disabled by configuration.
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "e1abba6d-7263-4046-9fe0-ef5b42e24bf2"
|
||
|
|
statusCode: 503
|
||
|
|
message: "HTTP request timeout"
|
||
|
|
delete:
|
||
|
|
summary: "Stop the ongoing device discovery process"
|
||
|
|
parameters:
|
||
|
|
- $ref: '#/components/parameters/correlatedRequestHeader'
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: "OK"
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "9dae40d3-902f-49e5-b532-1b20d36d1f05"
|
||
|
|
statusCode: 200
|
||
|
|
'500':
|
||
|
|
description: An unexpected error occurred on the server
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
500Example:
|
||
|
|
$ref: '#/components/examples/500Example'
|
||
|
|
'501':
|
||
|
|
description: Request is not supported
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
|
||
|
|
statusCode: 501
|
||
|
|
message: "Not implemented"
|
||
|
|
|
||
|
|
/discovery/requestId/{requestId}:
|
||
|
|
parameters:
|
||
|
|
- $ref: '#/components/parameters/correlatedRequestHeader'
|
||
|
|
- name: requestId
|
||
|
|
in: path
|
||
|
|
required: true
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
format: uuid
|
||
|
|
description: "An ID of datatype string, by default a GUID."
|
||
|
|
delete:
|
||
|
|
summary: "Stop the ongoing device discovery process with the specified request id"
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: "OK"
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "9dae40d3-902f-49e5-b532-1b20d36d1f05"
|
||
|
|
statusCode: 200
|
||
|
|
'404':
|
||
|
|
description: If the specified request id does not match the current working request id.
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
404Example:
|
||
|
|
$ref: '#/components/examples/404Example'
|
||
|
|
'500':
|
||
|
|
description: An unexpected error occurred on the server
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
500Example:
|
||
|
|
$ref: '#/components/examples/500Example'
|
||
|
|
'501':
|
||
|
|
description: Request is not supported
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
|
||
|
|
statusCode: 501
|
||
|
|
message: "Not implemented"
|
||
|
|
|
||
|
|
/profilescan:
|
||
|
|
parameters:
|
||
|
|
- $ref: '#/components/parameters/correlatedRequestHeader'
|
||
|
|
post:
|
||
|
|
description: Run the discovery request to generate a associated device profile for a specified device.
|
||
|
|
requestBody:
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/ProfileScanRequest'
|
||
|
|
required: true
|
||
|
|
responses:
|
||
|
|
'202':
|
||
|
|
description: "Request has been accepted"
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
|
||
|
|
statusCode: 202
|
||
|
|
message: "Device ProfileScan is triggered"
|
||
|
|
'400':
|
||
|
|
description: "Request is in an invalid state"
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "73f0932c-0148-11eb-adc1-0242ac120002"
|
||
|
|
statusCode: 400
|
||
|
|
message: "Bad Request"
|
||
|
|
'404':
|
||
|
|
description: "The requested resource does not exist."
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
400Example:
|
||
|
|
$ref: '#/components/examples/404Example'
|
||
|
|
'409':
|
||
|
|
description: "Conflict detected. Profile name must be universally unique or previous request is still processing."
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "8a41b3f4-0148-11eb-adc1-0242ac120002"
|
||
|
|
statusCode: 409
|
||
|
|
message: "Data Duplicate"
|
||
|
|
'423':
|
||
|
|
description: The device service is locked (admin state).
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
423Example:
|
||
|
|
$ref: '#/components/examples/423Example'
|
||
|
|
'500':
|
||
|
|
description: An unexpected error occurred on the server
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
500Example:
|
||
|
|
$ref: '#/components/examples/500Example'
|
||
|
|
'501':
|
||
|
|
description: Request is not supported
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
|
||
|
|
statusCode: 501
|
||
|
|
message: "Not implemented"
|
||
|
|
|
||
|
|
/profilescan/device/name/{name}:
|
||
|
|
parameters:
|
||
|
|
- $ref: '#/components/parameters/correlatedRequestHeader'
|
||
|
|
- name: name
|
||
|
|
in: path
|
||
|
|
required: true
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
description: "Uniquely identifies a given device"
|
||
|
|
delete:
|
||
|
|
summary: "Stop the ongoing device profile scanning process for a specific device"
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: "OK"
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "51e41bac-e405-4ee8-ad66-7741eb1e7b6d"
|
||
|
|
statusCode: 200
|
||
|
|
'404':
|
||
|
|
description: "The requested resource does not exist."
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
400Example:
|
||
|
|
$ref: '#/components/examples/404Example'
|
||
|
|
'423':
|
||
|
|
description: The device service is locked (admin state).
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
423Example:
|
||
|
|
$ref: '#/components/examples/423Example'
|
||
|
|
'500':
|
||
|
|
description: An unexpected error occurred on the server
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
500Example:
|
||
|
|
$ref: '#/components/examples/500Example'
|
||
|
|
'501':
|
||
|
|
description: Request is not supported
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
|
||
|
|
statusCode: 501
|
||
|
|
message: "Not implemented"
|
||
|
|
/config:
|
||
|
|
get:
|
||
|
|
summary: "Returns the current configuration of the service."
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: "OK"
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ConfigResponse'
|
||
|
|
'500':
|
||
|
|
description: Interval Server Error
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
500Example:
|
||
|
|
$ref: '#/components/examples/500Example'
|
||
|
|
|
||
|
|
/ping:
|
||
|
|
get:
|
||
|
|
summary: "A simple 'ping' endpoint that can be used as a service healthcheck"
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: "OK"
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/PingResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
timestamp: "Mon, 02 Jan 2006 15:04:05 MST"
|
||
|
|
serviceName: "device-gps"
|
||
|
|
'500':
|
||
|
|
description: Interval Server Error
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
500Example:
|
||
|
|
$ref: '#/components/examples/500Example'
|
||
|
|
|
||
|
|
/version:
|
||
|
|
get:
|
||
|
|
summary: "A simple 'version' endpoint that will return the current version of the service"
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: "OK"
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/VersionResponse'
|
||
|
|
example:
|
||
|
|
apiVersion: "v3"
|
||
|
|
version: "4.0.0"
|
||
|
|
"sdk_version": "4.0.0"
|
||
|
|
serviceName: "device-gps"
|
||
|
|
'500':
|
||
|
|
description: Interval Server Error
|
||
|
|
headers:
|
||
|
|
X-Correlation-ID:
|
||
|
|
$ref: '#/components/headers/correlatedResponseHeader'
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
examples:
|
||
|
|
500Example:
|
||
|
|
$ref: '#/components/examples/500Example'
|