380 lines
10 KiB
YAML
380 lines
10 KiB
YAML
openapi: 3.0.1
|
|
info:
|
|
title: Mainflux twins service
|
|
description: HTTP API for managing digital twins and their states.
|
|
version: '1.0.0'
|
|
|
|
paths:
|
|
/twins:
|
|
post:
|
|
summary: Adds new twin
|
|
description: |
|
|
Adds new twin to the list of twins owned by user identified using
|
|
the provided access token.
|
|
tags:
|
|
- twins
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/TwinReq"
|
|
responses:
|
|
'201':
|
|
$ref: "#/components/responses/TwinCreateRes"
|
|
'400':
|
|
description: Failed due to malformed JSON.
|
|
'401':
|
|
description: Missing or invalid access token provided.
|
|
'415':
|
|
description: Missing or invalid content type.
|
|
'500':
|
|
$ref: '#/components/responses/ServiceError'
|
|
|
|
get:
|
|
summary: Retrieves twins
|
|
description: |
|
|
Retrieves a list of twins. Due to performance concerns, data
|
|
is retrieved in subsets.
|
|
tags:
|
|
- twins
|
|
parameters:
|
|
- $ref: '#/components/parameters/Limit'
|
|
- $ref: '#/components/parameters/Offset'
|
|
- $ref: '#/components/parameters/Name'
|
|
- $ref: '#/components/parameters/Metadata'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/TwinsPageRes'
|
|
'400':
|
|
description: Failed due to malformed query parameters.
|
|
'401':
|
|
description: Missing or invalid access token provided.
|
|
'500':
|
|
$ref: '#/components/responses/ServiceError'
|
|
|
|
/twins/{twinID}:
|
|
get:
|
|
summary: Retrieves twin info
|
|
tags:
|
|
- twins
|
|
parameters:
|
|
- $ref: '#/components/parameters/TwinID'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/TwinRes'
|
|
'400':
|
|
description: Failed due to malformed twin's ID.
|
|
'401':
|
|
description: Missing or invalid access token provided.
|
|
'404':
|
|
description: Twin does not exist.
|
|
'500':
|
|
$ref: '#/components/responses/ServiceError'
|
|
put:
|
|
summary: Updates twin info
|
|
description: |
|
|
Update is performed by replacing the current resource data with values
|
|
provided in a request payload. Note that the twin's ID cannot be changed.
|
|
tags:
|
|
- twins
|
|
parameters:
|
|
- $ref: '#/components/parameters/TwinID'
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/TwinReq'
|
|
responses:
|
|
'200':
|
|
description: Twin updated.
|
|
'400':
|
|
description: Failed due to malformed twin's ID or malformed JSON.
|
|
'401':
|
|
description: Missing or invalid access token provided.
|
|
'404':
|
|
description: Twin does not exist.
|
|
'415':
|
|
description: Missing or invalid content type.
|
|
'500':
|
|
$ref: '#/components/responses/ServiceError'
|
|
delete:
|
|
summary: Removes a twin
|
|
description: Removes a twin.
|
|
tags:
|
|
- twins
|
|
parameters:
|
|
- $ref: '#/components/parameters/TwinID'
|
|
responses:
|
|
'204':
|
|
description: Twin removed.
|
|
'400':
|
|
description: Failed due to malformed twin's ID.
|
|
'401':
|
|
description: Missing or invalid access token provided
|
|
'404':
|
|
description: Twin does not exist.
|
|
'500':
|
|
$ref: '#/components/responses/ServiceError'
|
|
|
|
/states/{twinID}:
|
|
get:
|
|
summary: Retrieves states of twin with id twinID
|
|
description: |
|
|
Retrieves a list of states. Due to performance concerns, data
|
|
is retrieved in subsets.
|
|
tags:
|
|
- states
|
|
parameters:
|
|
- $ref: '#/components/parameters/TwinID'
|
|
- $ref: '#/components/parameters/Limit'
|
|
- $ref: '#/components/parameters/Offset'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/StatesPageRes'
|
|
'400':
|
|
description: Failed due to malformed query parameters.
|
|
'401':
|
|
description: Missing or invalid access token provided.
|
|
'404':
|
|
description: Twin does not exist.
|
|
'500':
|
|
$ref: '#/components/responses/ServiceError'
|
|
/health:
|
|
get:
|
|
summary: Retrieves service health check info.
|
|
tags:
|
|
- health
|
|
responses:
|
|
'200':
|
|
$ref: "#/components/responses/HealthRes"
|
|
'500':
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
components:
|
|
parameters:
|
|
Limit:
|
|
name: limit
|
|
description: Size of the subset to retrieve.
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 10
|
|
maximum: 100
|
|
minimum: 1
|
|
required: false
|
|
Offset:
|
|
name: offset
|
|
description: Number of items to skip during retrieval.
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
minimum: 0
|
|
required: false
|
|
Name:
|
|
name: name
|
|
description: Twin name
|
|
in: query
|
|
schema:
|
|
type: string
|
|
required: false
|
|
Metadata:
|
|
name: metadata
|
|
description: |
|
|
Metadata filter. Filtering is performed matching the parameter with
|
|
metadata on top level. Parameter is json.
|
|
in: query
|
|
schema:
|
|
type: string
|
|
minimum: 0
|
|
required: false
|
|
TwinID:
|
|
name: twinID
|
|
description: Unique twin identifier.
|
|
in: path
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
minimum: 1
|
|
required: true
|
|
|
|
schemas:
|
|
Attribute:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Name of the attribute.
|
|
channel:
|
|
type: string
|
|
description: Mainflux channel used by attribute.
|
|
subtopic:
|
|
type: string
|
|
description: Subtopic used by attribute.
|
|
persist_state:
|
|
type: boolean
|
|
description: Trigger state creation based on the attribute.
|
|
Definition:
|
|
type: object
|
|
properties:
|
|
delta:
|
|
type: number
|
|
description: Minimal time delay before new state creation.
|
|
attributes:
|
|
type: array
|
|
minItems: 0
|
|
uniqueItems: true
|
|
items:
|
|
$ref: '#/components/schemas/Attribute'
|
|
TwinReqObj:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Free-form twin name.
|
|
metadata:
|
|
type: object
|
|
description: Arbitrary, object-encoded twin's data.
|
|
definition:
|
|
$ref: '#/components/schemas/Definition'
|
|
TwinResObj:
|
|
type: object
|
|
properties:
|
|
owner:
|
|
type: string
|
|
description: Email address of Mainflux user that owns twin.
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique twin identifier generated by the service.
|
|
name:
|
|
type: string
|
|
description: Free-form twin name.
|
|
revision:
|
|
type: number
|
|
description: Oridnal revision number of twin.
|
|
created:
|
|
type: string
|
|
format: date
|
|
description: Twin creation date and time.
|
|
updated:
|
|
type: string
|
|
format: date
|
|
description: Twin update date and time.
|
|
definitions:
|
|
type: array
|
|
minItems: 0
|
|
uniqueItems: true
|
|
items:
|
|
$ref: '#/components/schemas/Definition'
|
|
metadata:
|
|
type: object
|
|
description: Arbitrary, object-encoded twin's data.
|
|
TwinsPage:
|
|
type: object
|
|
properties:
|
|
twins:
|
|
type: array
|
|
minItems: 0
|
|
uniqueItems: true
|
|
items:
|
|
$ref: '#/components/schemas/TwinResObj'
|
|
total:
|
|
type: integer
|
|
description: Total number of items.
|
|
offset:
|
|
type: integer
|
|
description: Number of items to skip during retrieval.
|
|
limit:
|
|
type: integer
|
|
description: Maximum number of items to return in one page.
|
|
required:
|
|
- twins
|
|
State:
|
|
type: object
|
|
properties:
|
|
twin_id:
|
|
type: string
|
|
format: uuid
|
|
description: ID of twin state belongs to.
|
|
id:
|
|
type: number
|
|
description: State position in a time row of states.
|
|
created:
|
|
type: string
|
|
format: date
|
|
description: State creation date.
|
|
payload:
|
|
type: object
|
|
description: Object-encoded states's payload.
|
|
StatesPage:
|
|
type: object
|
|
properties:
|
|
twins:
|
|
type: array
|
|
minItems: 0
|
|
uniqueItems: true
|
|
items:
|
|
$ref: '#/components/schemas/State'
|
|
total:
|
|
type: integer
|
|
description: Total number of items.
|
|
offset:
|
|
type: integer
|
|
description: Number of items to skip during retrieval.
|
|
limit:
|
|
type: integer
|
|
description: Maximum number of items to return in one page.
|
|
required:
|
|
- twins
|
|
|
|
requestBodies:
|
|
TwinReq:
|
|
description: JSON-formatted document describing the twin to create or update.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TwinReqObj'
|
|
required: true
|
|
|
|
responses:
|
|
TwinCreateRes:
|
|
description: Created twin's relative URL (i.e. /twins/{twinID}).
|
|
headers:
|
|
Location:
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
TwinRes:
|
|
description: Data retrieved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TwinResObj'
|
|
TwinsPageRes:
|
|
description: Data retrieved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TwinsPage'
|
|
StatesPageRes:
|
|
description: Data retrieved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/StatesPage'
|
|
ServiceError:
|
|
description: Unexpected server-side error occurred.
|
|
HealthRes:
|
|
description: Service Health Check.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "./schemas/HealthInfo.yml"
|
|
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
* Users access: "Authorization: Bearer <user_token>"
|
|
|
|
security:
|
|
- bearerAuth: []
|