mirror of
https://github.com/absmach/magistrala.git
synced 2026-08-07 07:14:46 +00:00
NOISSUE - Migrate swaggers to openapi 3 spec (#1250)
* Migrate authn swagger to openapi 3 Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Migrate http swagger to openapi 3 Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Migrate bootstrap swagger to openapi 3 Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Fix users spec parameters indentation Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Refactor user svc errs to return input related errors Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Migrate certs swagger to openapi 3 Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Migrate provision swagger to openapi 3 Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Migrate provision swagger to openapi 3 Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Migrate readers swagger to openapi 3 Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Migrate twins swagger to openapi 3 Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Refactor and rename bootstrap swagger Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Rename certs, http, provision and readers swagger to openapi Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Refactor and rename user swagger to openapi Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Refactor twins swagger and rename to openapi Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Refactor things swagger and rename to openapi Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com> * Cleanup whitespace Signed-off-by: Darko Draskovic <darko.draskovic@gmail.com>
This commit is contained in:
Darko Draskovic
GitHub
@@ -0,0 +1,147 @@
|
||||
openapi: 3.0.1
|
||||
info:
|
||||
title: Mainflux authentication service
|
||||
description: HTTP API for managing platform API keys.
|
||||
version: "1.0.0"
|
||||
|
||||
paths:
|
||||
/keys:
|
||||
post:
|
||||
summary: Issue API key
|
||||
description: |
|
||||
Generates a new API key. Thew new API key will
|
||||
be uniquely identified by its ID.
|
||||
tags:
|
||||
- authn
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/KeyRequest"
|
||||
responses:
|
||||
201:
|
||||
description: Issued new key.
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
409:
|
||||
description: Failed due to using already existing ID.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
/keys/{id}:
|
||||
get:
|
||||
summary: Gets API key details.
|
||||
description: |
|
||||
Gets API key details for the given key.
|
||||
tags:
|
||||
- authn
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ID"
|
||||
responses:
|
||||
200:
|
||||
$ref: "#/components/responses/KeyRes"
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
delete:
|
||||
summary: Revoke API key
|
||||
description: |
|
||||
Revoke API key identified by the given ID.
|
||||
tags:
|
||||
- authn
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ID"
|
||||
responses:
|
||||
204:
|
||||
description: Key revoked.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
|
||||
components:
|
||||
schemas:
|
||||
Key:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "c5747f2f-2a7c-4fe1-b41a-51a5ae290945"
|
||||
description: API key unique identifier
|
||||
type:
|
||||
type: integer
|
||||
example: 0
|
||||
description: API key type. Keys of different type are processed differently
|
||||
issuer:
|
||||
type: string
|
||||
format: string
|
||||
example: "test@example.com"
|
||||
description: User's email or service identifier of API key issuer
|
||||
secret:
|
||||
type: string
|
||||
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiZXhhbXBsZSIsImlhdCI6MTUxNjIzOTAyMn0.9UYAFWmPIn4ojss36LpIGSqABZHfADQmVuKQ4PJBMdI
|
||||
description: API Key value.
|
||||
issued_at:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2019-11-26 13:31:52"
|
||||
description: Time when the key is generated
|
||||
expires_at:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2019-11-26 13:31:52"
|
||||
description: Time when the Key expires
|
||||
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: Login key secret (User's access token).
|
||||
in: header
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
ID:
|
||||
name: id
|
||||
description: API Key id.
|
||||
in: path
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
|
||||
requestBodies:
|
||||
KeyRequest:
|
||||
description: JSON-formatted document describing key request.
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: integer
|
||||
example: 0
|
||||
description: API key type. Keys of different type are processed differently
|
||||
issuer:
|
||||
type: string
|
||||
format: e-mail
|
||||
example: "test@example.com"
|
||||
description: User's email or service identifier of API key issuer
|
||||
duration:
|
||||
type: number
|
||||
format: integer
|
||||
example: 23456
|
||||
description: Number of seconds issued token is valid for.
|
||||
|
||||
responses:
|
||||
ServiceError:
|
||||
description: Unexpected server-side error occurred.
|
||||
KeyRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Key"
|
||||
@@ -1,143 +0,0 @@
|
||||
swagger: "2.0"
|
||||
info:
|
||||
title: Mainflux authentication service
|
||||
description: HTTP API for managing platform API keys.
|
||||
version: "1.0.0"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
paths:
|
||||
/keys:
|
||||
post:
|
||||
summary: Issue API key
|
||||
description: |
|
||||
Generates a new API key. Thew new API key will
|
||||
be uniquely identified by its ID.
|
||||
tags:
|
||||
- authn
|
||||
parameters:
|
||||
- name: key
|
||||
description: JSON-formatted document describing the new key.
|
||||
in: body
|
||||
schema:
|
||||
$ref: "#/definitions/KeyRequest"
|
||||
required: true
|
||||
responses:
|
||||
201:
|
||||
description: Issued new key.
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
409:
|
||||
description: Failed due to using already existing ID.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
/keys/{id}:
|
||||
get:
|
||||
summary: Gets API key details.
|
||||
description: |
|
||||
Gets API key details for the given key.
|
||||
tags:
|
||||
- authn
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- name: id
|
||||
description: API Key id.
|
||||
in: path
|
||||
type: string
|
||||
required: true
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
schema:
|
||||
$ref: "#/definitions/Key"
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
delete:
|
||||
summary: Revoke API key
|
||||
description: |
|
||||
Revoke API key identified by the given ID.
|
||||
tags:
|
||||
- authn
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- name: id
|
||||
description: API Key id.
|
||||
in: path
|
||||
type: string
|
||||
required: true
|
||||
responses:
|
||||
204:
|
||||
description: Key revoked.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
|
||||
definitions:
|
||||
Key:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "c5747f2f-2a7c-4fe1-b41a-51a5ae290945"
|
||||
description: API key unique identifier
|
||||
type:
|
||||
type: integer
|
||||
example: 0
|
||||
description: API key type. Keys of different type are processed differently
|
||||
issuer:
|
||||
type: string
|
||||
format: string
|
||||
example: "test@example.com"
|
||||
description: User's email or service identifier of API key issuer
|
||||
secret:
|
||||
type: string
|
||||
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiZXhhbXBsZSIsImlhdCI6MTUxNjIzOTAyMn0.9UYAFWmPIn4ojss36LpIGSqABZHfADQmVuKQ4PJBMdI
|
||||
description: API Key value.
|
||||
issued_at:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2019-11-26 13:31:52"
|
||||
description: Time when the key is generated
|
||||
expires_at:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2019-11-26 13:31:52"
|
||||
description: Time when the Key expires
|
||||
KeyRequest:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: integer
|
||||
example: 0
|
||||
description: API key type. Keys of different type are processed differently
|
||||
issuer:
|
||||
type: string
|
||||
format: e-mail
|
||||
example: "test@example.com"
|
||||
description: User's email or service identifier of API key issuer
|
||||
duration:
|
||||
type: number
|
||||
format: integer
|
||||
example: 23456
|
||||
description: Number of seconds issued token is valid for.
|
||||
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: Login key secret (User's access token).
|
||||
in: header
|
||||
type: string
|
||||
required: true
|
||||
|
||||
responses:
|
||||
ServiceError:
|
||||
description: Unexpected server-side error occurred.
|
||||
@@ -0,0 +1,509 @@
|
||||
openapi: 3.0.1
|
||||
info:
|
||||
title: Mainflux Bootstrap service
|
||||
description: HTTP API for managing platform things configuration.
|
||||
version: "1.0.0"
|
||||
|
||||
paths:
|
||||
/things/configs:
|
||||
post:
|
||||
summary: Adds new config
|
||||
description: |
|
||||
Adds new config to the list of config owned by user identified using
|
||||
the provided access token.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/ConfigCreateReq"
|
||||
responses:
|
||||
201:
|
||||
$ref: "#/components/responses/ConfigCreateRes"
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
get:
|
||||
summary: Retrieves managed configs
|
||||
description: |
|
||||
Retrieves a list of managed configs. Due to performance concerns, data
|
||||
is retrieved in subsets. The API configs must ensure that the entire
|
||||
dataset is consumed either by making subsequent requests, or by
|
||||
increasing the subset size of the initial request.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/Limit"
|
||||
- $ref: "#/components/parameters/Offset"
|
||||
- $ref: "#/components/parameters/State"
|
||||
- $ref: "#/components/parameters/Name"
|
||||
responses:
|
||||
200:
|
||||
$ref: "#/components/responses/ConfigListRes"
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
/things/configs/{configId}:
|
||||
get:
|
||||
summary: Retrieves config info (with channels).
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ConfigId"
|
||||
responses:
|
||||
200:
|
||||
$ref: "#/components/responses/ConfigRes"
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Config does not exist.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
put:
|
||||
summary: Updates config info
|
||||
description: |
|
||||
Update is performed by replacing the current resource data with values
|
||||
provided in a request payload. Note that the owner, ID, external ID,
|
||||
external key, Mainflux Thing ID and key cannot be changed.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ConfigId"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/ConfigUpdateReq"
|
||||
responses:
|
||||
200:
|
||||
description: Config updated.
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Config does not exist.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
delete:
|
||||
summary: Removes a Config
|
||||
description: |
|
||||
Removes a Config. In case of successful removal the service will ensure
|
||||
that the removed config is disconnected from all of the Mainflux channels.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ConfigId"
|
||||
responses:
|
||||
204:
|
||||
description: Config removed.
|
||||
400:
|
||||
description: Failed due to malformed config ID.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
/things/configs/certs/{configId}:
|
||||
patch:
|
||||
summary: Updates certs
|
||||
description: |
|
||||
Update is performed by replacing the current certificate data with values
|
||||
provided in a request payload.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ConfigId"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/ConfigCertUpdateReq"
|
||||
responses:
|
||||
200:
|
||||
description: Config updated.
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Config does not exist.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
/things/configs/connections/{configId}:
|
||||
put:
|
||||
summary: Updates channels the thing is connected to
|
||||
description: |
|
||||
Update connections performs update of the channel list corresponding
|
||||
Thing is connected to.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ConfigId"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/ConfigConnUpdateReq"
|
||||
responses:
|
||||
200:
|
||||
description: Config updated.
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Config does not exist.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
/things/bootstrap/{externalId}:
|
||||
get:
|
||||
summary: Retrieves configuration.
|
||||
description: |
|
||||
Retrieves a configuration with given external ID and external key.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/ConfigAuth"
|
||||
- $ref: "#/components/parameters/ExternalId"
|
||||
responses:
|
||||
200:
|
||||
$ref: "#/components/responses/BootstrapConfigRes"
|
||||
404:
|
||||
description: |
|
||||
Failed to retrieve corresponding config.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
/things/bootstrap/secure/{externalId}:
|
||||
get:
|
||||
summary: Retrieves configuration.
|
||||
description: |
|
||||
Retrieves a configuration with given external ID and encrypted external key.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/EncConfigAuth"
|
||||
- $ref: "#/components/parameters/ExternalId"
|
||||
responses:
|
||||
200:
|
||||
$ref: "#/components/responses/BootstrapConfigRes"
|
||||
404:
|
||||
description: |
|
||||
Failed to retrieve corresponding config.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
/things/state/{configId}:
|
||||
put:
|
||||
summary: Updates Config state.
|
||||
description: |
|
||||
Updating state represents enabling/disabling Config, i.e. connecting
|
||||
and disconnecting corresponding Mainflux Thing to the list of Channels.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ConfigId"
|
||||
requestBody:
|
||||
$ref: '#/components/requestBodies/ConfigStateUpdateReq'
|
||||
responses:
|
||||
204:
|
||||
description: Config removed.
|
||||
400:
|
||||
description: Failed due to malformed config's ID.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
|
||||
components:
|
||||
schemas:
|
||||
State:
|
||||
type: integer
|
||||
enum: [0, 1]
|
||||
Config:
|
||||
type: object
|
||||
properties:
|
||||
mainflux_id:
|
||||
type: string
|
||||
description: Corresponding Mainflux Thing ID.
|
||||
mainflux_key:
|
||||
type: string
|
||||
description: Corresponding Mainflux Thing key.
|
||||
mainflux_channels:
|
||||
type: array
|
||||
minItems: 0
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: ID of the Channel.
|
||||
name:
|
||||
type: string
|
||||
description: Name of the Channel.
|
||||
metadata:
|
||||
type: object
|
||||
description: Custom metadata related to the Channel.
|
||||
external_id:
|
||||
type: string
|
||||
description: External ID (MAC address or some unique identifier).
|
||||
external_key:
|
||||
type: string
|
||||
description: External key.
|
||||
content:
|
||||
type: string
|
||||
description: Free-form custom configuration.
|
||||
state:
|
||||
$ref: "#/components/schemas/State"
|
||||
required:
|
||||
- external_id
|
||||
- external_key
|
||||
ConfigList:
|
||||
type: object
|
||||
properties:
|
||||
total:
|
||||
type: integer
|
||||
description: Total number of results.
|
||||
minimum: 0
|
||||
offset:
|
||||
type: integer
|
||||
description: Number of items to skip during retrieval.
|
||||
minimum: 0
|
||||
default: 0
|
||||
limit:
|
||||
type: integer
|
||||
description: Size of the subset to retrieve.
|
||||
maximum: 100
|
||||
default: 10
|
||||
configs:
|
||||
type: array
|
||||
minItems: 0
|
||||
uniqueItems: true
|
||||
items:
|
||||
$ref: "#/components/schemas/Config"
|
||||
required:
|
||||
- configs
|
||||
BootstrapConfig:
|
||||
type: object
|
||||
properties:
|
||||
mainflux_id:
|
||||
type: string
|
||||
description: Corresponding Mainflux Thing ID.
|
||||
mainflux_key:
|
||||
type: string
|
||||
description: Corresponding Mainflux Thing key.
|
||||
mainflux_channels:
|
||||
type: array
|
||||
minItems: 0
|
||||
items:
|
||||
type: string
|
||||
content:
|
||||
type: string
|
||||
description: Free-form custom configuration.
|
||||
client_cert:
|
||||
type: string
|
||||
description: Client certificate.
|
||||
client_key:
|
||||
type: string
|
||||
description: Key for the client_cert.
|
||||
ca_cert:
|
||||
type: string
|
||||
description: Issuing CA certificate.
|
||||
required:
|
||||
- mainflux_id
|
||||
- mainflux_key
|
||||
- mainflux_channels
|
||||
- content
|
||||
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: User's access token.
|
||||
in: header
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
ConfigAuth:
|
||||
name: configAuthorization
|
||||
description: Configuration external key.
|
||||
in: header
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
EncConfigAuth:
|
||||
name: configAuthorization
|
||||
description: |
|
||||
Hex-encoded configuration external key encrypted using
|
||||
the AES algorithm and SHA256 sum of the external key
|
||||
itself as an encryption key.
|
||||
in: header
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
ConfigId:
|
||||
name: configId
|
||||
description: Unique Config identifier. It's the ID of the corresponding Thing.
|
||||
in: path
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
ExternalId:
|
||||
name: externalId
|
||||
description: Unique Config identifier provided by external entity.
|
||||
in: path
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
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
|
||||
State:
|
||||
name: state
|
||||
description: A state of items
|
||||
in: query
|
||||
schema:
|
||||
$ref: "#/components/schemas/State"
|
||||
required: false
|
||||
Name:
|
||||
name: name
|
||||
description: Name of the config. Search by name is partial-match and case-insensitive.
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
required: false
|
||||
|
||||
requestBodies:
|
||||
ConfigCreateReq:
|
||||
description: JSON-formatted document describing the new config.
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
external_id:
|
||||
type: string
|
||||
description: External ID (MAC address or some unique identifier).
|
||||
external_key:
|
||||
type: string
|
||||
description: External key.
|
||||
thing_id:
|
||||
type: string
|
||||
description: ID of the corresponding Mainflux Thing.
|
||||
channels:
|
||||
type: array
|
||||
minItems: 0
|
||||
items:
|
||||
type: string
|
||||
content:
|
||||
type: string
|
||||
required:
|
||||
- external_id
|
||||
- external_key
|
||||
ConfigUpdateReq:
|
||||
description: JSON-formatted document describing the updated thing.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
content:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
required:
|
||||
- content
|
||||
- name
|
||||
ConfigCertUpdateReq:
|
||||
description: JSON-formatted document describing the updated thing.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
client_cert:
|
||||
type: string
|
||||
client_key:
|
||||
type: string
|
||||
ca_cert:
|
||||
type: string
|
||||
ConfigConnUpdateReq:
|
||||
description: Array if IDs the thing is be connected to.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
channels:
|
||||
type: array
|
||||
minItems: 0
|
||||
items:
|
||||
type: string
|
||||
ConfigStateUpdateReq:
|
||||
description: Update the state of the Config.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
state:
|
||||
$ref: "#/components/schemas/State"
|
||||
|
||||
responses:
|
||||
ConfigCreateRes:
|
||||
description: Config registered.
|
||||
headers:
|
||||
Location:
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
description: Created configuration's relative URL (i.e. /things/configs/{configId}).
|
||||
ConfigListRes:
|
||||
description: Data retrieved. Configs from this list don't contain channels.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ConfigList"
|
||||
ConfigRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Config"
|
||||
BootstrapConfigRes:
|
||||
description: |
|
||||
Data retrieved. If secure, a response is encrypted using
|
||||
the secret key, so the response is in the binary form.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/BootstrapConfig"
|
||||
ServiceError:
|
||||
description: Unexpected server-side error occurred.
|
||||
@@ -1,491 +0,0 @@
|
||||
swagger: "2.0"
|
||||
info:
|
||||
title: Mainflux Bootstrap service
|
||||
description: HTTP API for managing platform things configuration.
|
||||
version: "1.0.0"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
paths:
|
||||
/things/configs:
|
||||
post:
|
||||
summary: Adds new config
|
||||
description: |
|
||||
Adds new config to the list of config owned by user identified using
|
||||
the provided access token.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- name: config
|
||||
description: JSON-formatted document describing the new config.
|
||||
in: body
|
||||
schema:
|
||||
$ref: "#/definitions/ConfigReq"
|
||||
required: true
|
||||
responses:
|
||||
201:
|
||||
description: Config registered.
|
||||
headers:
|
||||
Location:
|
||||
type: string
|
||||
description: Created configuration's relative URL (i.e. /things/configs/{configId}).
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
get:
|
||||
summary: Retrieves managed configs
|
||||
description: |
|
||||
Retrieves a list of managed configs. Due to performance concerns, data
|
||||
is retrieved in subsets. The API configs must ensure that the entire
|
||||
dataset is consumed either by making subsequent requests, or by
|
||||
increasing the subset size of the initial request.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- $ref: "#/parameters/Limit"
|
||||
- $ref: "#/parameters/Offset"
|
||||
- $ref: "#/parameters/State"
|
||||
- $ref: "#/parameters/Name"
|
||||
responses:
|
||||
200:
|
||||
description: |
|
||||
Data retrieved. Configs from this list don't contain channels.
|
||||
schema:
|
||||
$ref: "#/definitions/ConfigList"
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
/things/bootstrap/{externalId}:
|
||||
get:
|
||||
summary: Retrieves configuration
|
||||
description: |
|
||||
Retrieves a configuration with given external ID and external key.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/ConfigAuth"
|
||||
- $ref: "#/parameters/ExternalId"
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
schema:
|
||||
$ref: "#/definitions/BootstrapRes"
|
||||
404:
|
||||
description: |
|
||||
Failed to retrieve corresponding config.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
/things/bootstrap/secure/{externalId}:
|
||||
get:
|
||||
summary: Retrieves configuration
|
||||
description: |
|
||||
Retrieves a configuration with given external ID and encrypted external key.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/EncConfigAuth"
|
||||
- $ref: "#/parameters/ExternalId"
|
||||
responses:
|
||||
200:
|
||||
description: |
|
||||
Data retrieved. In this case, Bootstrap response is encrypted using
|
||||
the secret key, so an actual response is in the binary format.
|
||||
schema:
|
||||
$ref: "#/definitions/BootstrapRes"
|
||||
404:
|
||||
description: |
|
||||
Failed to retrieve corresponding config.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
/things/configs/{configId}:
|
||||
get:
|
||||
summary: Retrieves config info (with channels)
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- $ref: "#/parameters/ConfigId"
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
schema:
|
||||
$ref: "#/definitions/ConfigRes"
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Config does not exist.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
put:
|
||||
summary: Updates config info
|
||||
description: |
|
||||
Update is performed by replacing the current resource data with values
|
||||
provided in a request payload. Note that the owner, ID, external ID,
|
||||
external key, Mainflux Thing ID and key cannot be changed.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- $ref: "#/parameters/ConfigId"
|
||||
- name: config
|
||||
description: JSON-formatted document describing the updated thing.
|
||||
in: body
|
||||
schema:
|
||||
$ref: "#/definitions/ConfigUpdateReq"
|
||||
required: true
|
||||
responses:
|
||||
200:
|
||||
description: Config updated.
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Config does not exist.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
delete:
|
||||
summary: Removes a Config
|
||||
description: |
|
||||
Removes a Config. In case of successful removal the service will ensure
|
||||
that the removed config is disconnected from all of the Mainflux channels.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- $ref: "#/parameters/ConfigId"
|
||||
responses:
|
||||
204:
|
||||
description: Config removed.
|
||||
400:
|
||||
description: Failed due to malformed config ID.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
/things/configs/certs/{configId}:
|
||||
patch:
|
||||
summary: Updates certs
|
||||
description: |
|
||||
Update is performed by replacing the current certificate data with values
|
||||
provided in a request payload.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- $ref: "#/parameters/ConfigId"
|
||||
- name: config
|
||||
description: JSON-formatted document describing the updated thing.
|
||||
in: body
|
||||
schema:
|
||||
$ref: "#/definitions/ConfigUpdateCertReq"
|
||||
required: true
|
||||
responses:
|
||||
200:
|
||||
description: Config updated.
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Config does not exist.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
/things/configs/connections/{configId}:
|
||||
put:
|
||||
summary: Updates channels the thing is connected to
|
||||
description: |
|
||||
Update connections performs update of the channel list corresponding
|
||||
Thing is connected to.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- $ref: "#/parameters/ConfigId"
|
||||
- name: channels
|
||||
description: Array if IDs the thing is be connected to.
|
||||
in: body
|
||||
schema:
|
||||
$ref: "#/definitions/ConfigUpdateConnReq"
|
||||
required: true
|
||||
responses:
|
||||
200:
|
||||
description: Config updated.
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Config does not exist.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
/things/state/{configId}:
|
||||
put:
|
||||
summary: Updates Config state.
|
||||
description: |
|
||||
Updating state represents enabling/disabling Config, i.e. connecting
|
||||
and disconnecting corresponding Mainflux Thing to the list of Channels.
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- $ref: "#/parameters/ConfigId"
|
||||
- name: state
|
||||
description: New state of the Config.
|
||||
in: body
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
state:
|
||||
type: integer
|
||||
enum:
|
||||
- inactive
|
||||
- active
|
||||
responses:
|
||||
204:
|
||||
description: Config removed.
|
||||
400:
|
||||
description: Failed due to malformed config's ID.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: User's access token.
|
||||
in: header
|
||||
type: string
|
||||
required: true
|
||||
ConfigAuth:
|
||||
name: configAuthorization
|
||||
description: Configuration external key.
|
||||
in: header
|
||||
type: string
|
||||
required: true
|
||||
EncConfigAuth:
|
||||
name: configAuthorization
|
||||
description: |
|
||||
Hex-encoded configuration external key encrypted using
|
||||
the AES algorithm and SHA256 sum of the external key
|
||||
itself as an encryption key.
|
||||
in: header
|
||||
type: string
|
||||
required: true
|
||||
ConfigId:
|
||||
name: configId
|
||||
description: Unique Config identifier. It's the ID of the corresponding Thing.
|
||||
in: path
|
||||
type: string
|
||||
required: true
|
||||
ExternalId:
|
||||
name: externalId
|
||||
description: Unique Config identifier provided by external entity.
|
||||
in: path
|
||||
type: string
|
||||
required: true
|
||||
Limit:
|
||||
name: limit
|
||||
description: Size of the subset to retrieve.
|
||||
in: query
|
||||
type: integer
|
||||
default: 10
|
||||
maximum: 100
|
||||
minimum: 1
|
||||
required: false
|
||||
Offset:
|
||||
name: offset
|
||||
description: Number of items to skip during retrieval.
|
||||
in: query
|
||||
type: integer
|
||||
default: 0
|
||||
minimum: 0
|
||||
required: false
|
||||
State:
|
||||
name: state
|
||||
description: A state of items
|
||||
in: query
|
||||
type: integer
|
||||
enum:
|
||||
- inactive
|
||||
- active
|
||||
required: false
|
||||
Name:
|
||||
name: name
|
||||
description: Name of the config. Search by name is partial-match and case-insensitive.
|
||||
in: query
|
||||
type: string
|
||||
required: false
|
||||
|
||||
responses:
|
||||
ServiceError:
|
||||
description: Unexpected server-side error occurred.
|
||||
|
||||
definitions:
|
||||
ConfigList:
|
||||
type: object
|
||||
properties:
|
||||
total:
|
||||
type: integer
|
||||
description: Total number of results.
|
||||
minimum: 0
|
||||
offset:
|
||||
type: integer
|
||||
description: Number of items to skip during retrieval.
|
||||
minimum: 0
|
||||
default: 0
|
||||
limit:
|
||||
type: integer
|
||||
description: Size of the subset to retrieve.
|
||||
maximum: 100
|
||||
default: 10
|
||||
configs:
|
||||
type: array
|
||||
minItems: 0
|
||||
uniqueItems: true
|
||||
items:
|
||||
$ref: "#/definitions/ConfigRes"
|
||||
required:
|
||||
- configs
|
||||
State:
|
||||
type: integer
|
||||
enum:
|
||||
- active
|
||||
- inactive
|
||||
ConfigRes:
|
||||
type: object
|
||||
properties:
|
||||
mainflux_id:
|
||||
type: string
|
||||
description: Corresponding Mainflux Thing ID.
|
||||
mainflux_key:
|
||||
type: string
|
||||
description: Corresponding Mainflux Thing key.
|
||||
mainflux_channels:
|
||||
type: array
|
||||
minItems: 0
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: ID of the Channel.
|
||||
name:
|
||||
type: string
|
||||
description: Name of the Channel.
|
||||
metadata:
|
||||
type: object
|
||||
description: Custom metadata related to the Channel.
|
||||
external_id:
|
||||
type: string
|
||||
description: External ID (MAC address or some unique identifier).
|
||||
external_key:
|
||||
type: string
|
||||
description: External key.
|
||||
content:
|
||||
type: string
|
||||
description: Free-form custom configuration.
|
||||
state:
|
||||
$ref: '#/definitions/State'
|
||||
required:
|
||||
- external_id
|
||||
- external_key
|
||||
BootstrapRes:
|
||||
type: object
|
||||
properties:
|
||||
mainflux_id:
|
||||
type: string
|
||||
description: Corresponding Mainflux Thing ID.
|
||||
mainflux_key:
|
||||
type: string
|
||||
description: Corresponding Mainflux Thing key.
|
||||
mainflux_channels:
|
||||
type: array
|
||||
minItems: 0
|
||||
items:
|
||||
type: string
|
||||
content:
|
||||
type: string
|
||||
description: Free-form custom configuration.
|
||||
client_cert:
|
||||
type: string
|
||||
description: Client certificate.
|
||||
client_key:
|
||||
type: string
|
||||
description: Key for the client_cert.
|
||||
ca_cert:
|
||||
type: string
|
||||
description: Issuing CA certificate.
|
||||
required:
|
||||
- mainflux_id
|
||||
- mainflux_key
|
||||
- mainflux_channels
|
||||
- content
|
||||
|
||||
ConfigReq:
|
||||
type: object
|
||||
properties:
|
||||
external_id:
|
||||
type: string
|
||||
description: External ID (MAC address or some unique identifier).
|
||||
external_key:
|
||||
type: string
|
||||
description: External key.
|
||||
thing_id:
|
||||
type: string
|
||||
description: ID of the corresponding Mainflux Thing.
|
||||
channels:
|
||||
type: array
|
||||
minItems: 0
|
||||
items:
|
||||
type: string
|
||||
content:
|
||||
type: string
|
||||
required:
|
||||
- external_id
|
||||
- external_key
|
||||
ConfigUpdateReq:
|
||||
type: object
|
||||
properties:
|
||||
content:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
required:
|
||||
- content
|
||||
- name
|
||||
ConfigUpdateConnReq:
|
||||
type: object
|
||||
properties:
|
||||
channels:
|
||||
type: array
|
||||
minItems: 0
|
||||
items:
|
||||
type: string
|
||||
ConfigUpdateCertReq:
|
||||
type: object
|
||||
properties:
|
||||
client_cert:
|
||||
type: string
|
||||
client_key:
|
||||
type: string
|
||||
ca_cert:
|
||||
type: string
|
||||
@@ -0,0 +1,144 @@
|
||||
openapi: 3.0.1
|
||||
info:
|
||||
title: Mainflux Certs service
|
||||
description: HTTP API for Certs service
|
||||
version: "1.0.0"
|
||||
|
||||
paths:
|
||||
/certs:
|
||||
post:
|
||||
summary: Creates a certificate for thing
|
||||
description: Creates a certificate for thing
|
||||
tags:
|
||||
- Thing to proxy
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/CertReq"
|
||||
responses:
|
||||
201:
|
||||
description: Created
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
500:
|
||||
description: Unexpected server-side error ocurred.
|
||||
/certs/{thingID}:
|
||||
get:
|
||||
summary: Retrieves certificates
|
||||
description: |
|
||||
Retrieves a certificates for given thing ID .
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ThingID"
|
||||
responses:
|
||||
200:
|
||||
$ref: "#/components/responses/CertsRes"
|
||||
404:
|
||||
description: |
|
||||
Failed to retrieve corresponding certificate.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
/certs/revoke:
|
||||
delete:
|
||||
summary: Revokes certificate
|
||||
description: |
|
||||
Revokes a certificates for given thing ID .
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ThingID"
|
||||
responses:
|
||||
200:
|
||||
$ref: "#/components/responses/RevokeRes"
|
||||
404:
|
||||
description: |
|
||||
Failed to revoke corresponding certificate.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
|
||||
components:
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: User's access token. Used instead of credentials in env or config.toml.
|
||||
in: header
|
||||
schema:
|
||||
type: string
|
||||
required: false
|
||||
ThingID:
|
||||
name: thingID
|
||||
description: Thing ID
|
||||
in: path
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
|
||||
schemas:
|
||||
Certs:
|
||||
type: object
|
||||
properties:
|
||||
thing_id:
|
||||
type: string
|
||||
description: Corresponding Mainflux Thing ID.
|
||||
client_cert:
|
||||
type: string
|
||||
description: Client Certificate.
|
||||
client_key:
|
||||
type: string
|
||||
description: Key for the client_cert.
|
||||
issuing_ca:
|
||||
type: string
|
||||
description: CA Certificate that is used to issue client certs, usually intermediate.
|
||||
serial:
|
||||
type: string
|
||||
description: Certificate serial
|
||||
expire:
|
||||
type: string
|
||||
description: Certificate expiry date
|
||||
Revoke:
|
||||
type: object
|
||||
properties:
|
||||
revocation_time:
|
||||
type: string
|
||||
description: Certificate revocation time
|
||||
|
||||
requestBodies:
|
||||
CertReq:
|
||||
description: |
|
||||
Issues a certificate that is required for mTLS. To create a certificate for a thing
|
||||
provide a thing id, data identifying particular thing will be embedded into the Certificate.
|
||||
x509 and ECC certificates are supported when using when Vault is used as PKI.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required:
|
||||
- thing_id
|
||||
- days_valid
|
||||
- rsa_bits
|
||||
properties:
|
||||
thing_id:
|
||||
type: string
|
||||
days_valid:
|
||||
type: string
|
||||
rsa_bits:
|
||||
type: integer
|
||||
|
||||
responses:
|
||||
ServiceError:
|
||||
description: Unexpected server-side error occurred.
|
||||
CertsRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Certs"
|
||||
RevokeRes:
|
||||
description: Certificate revoked.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Revoke"
|
||||
@@ -1,130 +0,0 @@
|
||||
swagger: "2.0"
|
||||
info:
|
||||
title: Mainflux Certs service
|
||||
description: HTTP API for Certs service
|
||||
version: "1.0.0"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
paths:
|
||||
/certs:
|
||||
post:
|
||||
consumes:
|
||||
- application/json
|
||||
summary: Creates a certificate for thing
|
||||
description: Creates a certificate for thing
|
||||
tags:
|
||||
- Thing to proxy
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- in: body
|
||||
name: cert
|
||||
description: |
|
||||
Issues a certificate that is required for mTLS. To create a certificate for a thing
|
||||
provide a thing id, data identifying particular thing will be embedded into the Certificate.
|
||||
x509 and ECC certificates are supported when using when Vault is used as PKI.
|
||||
schema:
|
||||
type: object
|
||||
required:
|
||||
- thing_id
|
||||
- days_valid
|
||||
- rsa_bits
|
||||
properties:
|
||||
thing_id:
|
||||
type: string
|
||||
days_valid:
|
||||
type: string
|
||||
rsa_bits:
|
||||
type: integer
|
||||
responses:
|
||||
201:
|
||||
description: Created
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
500:
|
||||
description: Unexpected server-side error ocurred.
|
||||
/certs/{thingID}:
|
||||
get:
|
||||
summary: Retrieves certificates
|
||||
description: |
|
||||
Retrieves a certificates for given thing ID .
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- $ref: "#/parameters/ThingID"
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
schema:
|
||||
$ref: "#/definitions/CertsRes"
|
||||
404:
|
||||
description: |
|
||||
Failed to retrieve corresponding certificate.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
/certs/revoke:
|
||||
delete:
|
||||
summary: Revokes certificate
|
||||
description: |
|
||||
Revokes a certificates for given thing ID .
|
||||
tags:
|
||||
- configs
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- $ref: "#/parameters/ThingID"
|
||||
responses:
|
||||
200:
|
||||
description: Certificate revoked.
|
||||
schema:
|
||||
$ref: "#/definitions/RevokeRes"
|
||||
404:
|
||||
description: |
|
||||
Failed to revoke corresponding certificate.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: User's access token. Used instead of credentials in env or config.toml.
|
||||
in: header
|
||||
type: string
|
||||
required: false
|
||||
ThingID:
|
||||
name: thingID
|
||||
description: Thing ID
|
||||
in: path
|
||||
type: string
|
||||
required: true
|
||||
definitions:
|
||||
CertsRes:
|
||||
type: object
|
||||
properties:
|
||||
thing_id:
|
||||
type: string
|
||||
description: Corresponding Mainflux Thing ID.
|
||||
client_cert:
|
||||
type: string
|
||||
description: Client Certificate.
|
||||
client_key:
|
||||
type: string
|
||||
description: Key for the client_cert.
|
||||
issuing_ca:
|
||||
type: string
|
||||
description: CA Certificate that is used to issue client certs, usually intermediate.
|
||||
serial:
|
||||
type: string
|
||||
description: Certificate serial
|
||||
expire:
|
||||
type: string
|
||||
description: Certificate expiry date
|
||||
RevokeRes:
|
||||
type: object
|
||||
properties:
|
||||
revocation_time:
|
||||
type: string
|
||||
description: Certificate revocation time
|
||||
responses:
|
||||
ServiceError:
|
||||
description: Unexpected server-side error occurred.
|
||||
@@ -0,0 +1,127 @@
|
||||
openapi: 3.0.1
|
||||
info:
|
||||
title: Mainflux http adapter
|
||||
description: HTTP API for sending messages through communication channels.
|
||||
version: "1.0.0"
|
||||
paths:
|
||||
/channels/{id}/messages:
|
||||
post:
|
||||
summary: Sends message to the communication channel
|
||||
description: |
|
||||
Sends message to the communication channel. Messages can be sent as
|
||||
JSON formatted SenML or as blob.
|
||||
tags:
|
||||
- messages
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ID"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/MessageReq"
|
||||
responses:
|
||||
202:
|
||||
description: Message is accepted for processing.
|
||||
400:
|
||||
description: Message discarded due to its malformed content.
|
||||
403:
|
||||
description: Message discarded due to missing or invalid credentials.
|
||||
404:
|
||||
description: Message discarded due to invalid channel id.
|
||||
415:
|
||||
description: Message discarded due to invalid or missing content type.
|
||||
500:
|
||||
description: Unexpected server-side error occurred.
|
||||
|
||||
components:
|
||||
schemas:
|
||||
SenMLRecord:
|
||||
type: object
|
||||
properties:
|
||||
bn:
|
||||
type: string
|
||||
description: Base Name
|
||||
bt:
|
||||
type: number
|
||||
format: double
|
||||
description: Base Time
|
||||
bu:
|
||||
type: number
|
||||
format: double
|
||||
description: Base Unit
|
||||
bv:
|
||||
type: number
|
||||
format: double
|
||||
description: Base Value
|
||||
bs:
|
||||
type: number
|
||||
format: double
|
||||
description: Base Sum
|
||||
bver:
|
||||
type: number
|
||||
format: double
|
||||
description: Version
|
||||
n:
|
||||
type: string
|
||||
description: Name
|
||||
u:
|
||||
type: string
|
||||
description: Unit
|
||||
v:
|
||||
type: number
|
||||
format: double
|
||||
description: Value
|
||||
vs:
|
||||
type: string
|
||||
description: String Value
|
||||
vb:
|
||||
type: boolean
|
||||
description: Boolean Value
|
||||
vd:
|
||||
type: string
|
||||
description: Data Value
|
||||
s:
|
||||
type: number
|
||||
format: double
|
||||
description: Value Sum
|
||||
t:
|
||||
type: number
|
||||
format: double
|
||||
description: Time
|
||||
ut:
|
||||
type: number
|
||||
format: double
|
||||
description: Update Time
|
||||
SenMLArray:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/SenMLRecord"
|
||||
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: Access token.
|
||||
in: header
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
ID:
|
||||
name: id
|
||||
description: Unique channel identifier.
|
||||
in: path
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
required: true
|
||||
|
||||
requestBodies:
|
||||
MessageReq:
|
||||
description: |
|
||||
Message to be distributed. Since the platform expects messages to be
|
||||
properly formatted SenML in order to be post-processed, clients are
|
||||
obliged to specify Content-Type header for each published message.
|
||||
Note that all messages that aren't SenML will be accepted and published,
|
||||
but no post-processing will be applied.
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/SenMLArray"
|
||||
@@ -1,116 +0,0 @@
|
||||
swagger: "2.0"
|
||||
info:
|
||||
title: Mainflux http adapter
|
||||
description: HTTP API for sending messages through communication channels.
|
||||
version: "1.0.0"
|
||||
paths:
|
||||
/channels/{id}/messages:
|
||||
post:
|
||||
summary: Sends message to the communication channel
|
||||
description: |
|
||||
Sends message to the communication channel. Messages can be sent as
|
||||
JSON formatted SenML or as blob.
|
||||
tags:
|
||||
- messages
|
||||
consumes:
|
||||
- "application/senml+json"
|
||||
- "text/plain"
|
||||
produces: []
|
||||
parameters:
|
||||
- name: Authorization
|
||||
description: Access token.
|
||||
in: header
|
||||
type: string
|
||||
required: true
|
||||
- name: id
|
||||
description: Unique channel identifier.
|
||||
in: path
|
||||
type: string
|
||||
format: uuid
|
||||
required: true
|
||||
- name: message
|
||||
description: |
|
||||
Message to be distributed. Since the platform expects messages to be
|
||||
properly formatted SenML in order to be post-processed, clients are
|
||||
obliged to specify Content-Type header for each published message.
|
||||
Note that all messages that aren't SenML will be accepted and published,
|
||||
but no post-processing will be applied.
|
||||
in: body
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/SenMLArray'
|
||||
responses:
|
||||
202:
|
||||
description: Message is accepted for processing.
|
||||
400:
|
||||
description: Message discarded due to its malformed content.
|
||||
403:
|
||||
description: Message discarded due to missing or invalid credentials.
|
||||
404:
|
||||
description: Message discarded due to invalid channel id.
|
||||
415:
|
||||
description: Message discarded due to invalid or missing content type.
|
||||
500:
|
||||
description: Unexpected server-side error occurred.
|
||||
definitions:
|
||||
SenMLRecord:
|
||||
type: object
|
||||
properties:
|
||||
bn:
|
||||
type: string
|
||||
description: Base Name
|
||||
bt:
|
||||
type: number
|
||||
format: double
|
||||
description: Base Time
|
||||
bu:
|
||||
type: number
|
||||
format: double
|
||||
description: Base Unit
|
||||
bv:
|
||||
type: number
|
||||
format: double
|
||||
description: Base Value
|
||||
bs:
|
||||
type: number
|
||||
format: double
|
||||
description: Base Sum
|
||||
bver:
|
||||
type: number
|
||||
format: double
|
||||
description: Version
|
||||
n:
|
||||
type: string
|
||||
description: Name
|
||||
u:
|
||||
type: string
|
||||
description: Unit
|
||||
v:
|
||||
type: number
|
||||
format: double
|
||||
description: Value
|
||||
vs:
|
||||
type: string
|
||||
description: String Value
|
||||
vb:
|
||||
type: boolean
|
||||
description: Boolean Value
|
||||
vd:
|
||||
type: string
|
||||
description: Data Value
|
||||
s:
|
||||
type: number
|
||||
format: double
|
||||
description: Value Sum
|
||||
t:
|
||||
type: number
|
||||
format: double
|
||||
description: Time
|
||||
ut:
|
||||
type: number
|
||||
format: double
|
||||
description: Update Time
|
||||
SenMLArray:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/definitions/SenMLRecord"
|
||||
@@ -0,0 +1,79 @@
|
||||
openapi: 3.0.1
|
||||
info:
|
||||
title: Mainflux Provision service
|
||||
description: HTTP API for Provision service
|
||||
version: "1.0.0"
|
||||
|
||||
paths:
|
||||
/mapping:
|
||||
post:
|
||||
summary: Adds new device to proxy
|
||||
description: Adds new device to proxy
|
||||
tags:
|
||||
- provision
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/ProvisionReq"
|
||||
responses:
|
||||
201:
|
||||
description: Created
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Unauthorized.
|
||||
500:
|
||||
description: Unexpected server-side error ocurred.
|
||||
get:
|
||||
summary: Gets current mapping.
|
||||
description: Gets current mapping. This can be used in UI
|
||||
so that when bootstrap config is created from UI matches
|
||||
configuration created with provision service.
|
||||
tags:
|
||||
- provision
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
responses:
|
||||
200:
|
||||
$ref: "#/components/responses/ProvisionRes"
|
||||
403:
|
||||
description: Unauthorized.
|
||||
500:
|
||||
description: Unexpected server-side error ocurred.
|
||||
|
||||
components:
|
||||
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: User's access token. Used instead of credentials in env or config.toml.
|
||||
in: header
|
||||
schema:
|
||||
type: string
|
||||
required: false
|
||||
|
||||
requestBodies:
|
||||
ProvisionReq:
|
||||
description: MAC address of device or other identifier
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required:
|
||||
- external_id
|
||||
- external_key
|
||||
properties:
|
||||
external_id:
|
||||
type: string
|
||||
external_key:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
|
||||
responses:
|
||||
ProvisionRes:
|
||||
description: Current mapping JSON representation.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
@@ -1,76 +0,0 @@
|
||||
swagger: "2.0"
|
||||
info:
|
||||
title: Mainflux Provision service
|
||||
description: HTTP API for Provision service
|
||||
version: "1.0.0"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
paths:
|
||||
/mapping:
|
||||
post:
|
||||
consumes:
|
||||
- application/json
|
||||
summary: Adds new device to proxy
|
||||
description: Adds new device to proxy
|
||||
tags:
|
||||
- provision
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- in: body
|
||||
name: thing
|
||||
description: MAC address of device or other identifier
|
||||
schema:
|
||||
type: object
|
||||
required:
|
||||
- external_id
|
||||
- external_key
|
||||
properties:
|
||||
external_id:
|
||||
type: string
|
||||
external_key:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
responses:
|
||||
201:
|
||||
description: Created
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Unauthorized.
|
||||
500:
|
||||
description: Unexpected server-side error ocurred.
|
||||
get:
|
||||
consumes:
|
||||
- application/json
|
||||
summary: Gets current mapping.
|
||||
description: Gets current mapping. This can be used in UI
|
||||
so that when bootstrap config is created from UI matches
|
||||
configuration created with provision service.
|
||||
tags:
|
||||
- provision
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
responses:
|
||||
200:
|
||||
schema:
|
||||
$ref: "#/definitions/Content"
|
||||
description: retrieved
|
||||
403:
|
||||
description: Unauthorized.
|
||||
500:
|
||||
description: Unexpected server-side error ocurred.
|
||||
|
||||
definitions:
|
||||
Content:
|
||||
type: object
|
||||
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: User's access token. Used instead of credentials in env or config.toml.
|
||||
in: header
|
||||
type: string
|
||||
required: false
|
||||
@@ -0,0 +1,136 @@
|
||||
openapi: 3.0.1
|
||||
info:
|
||||
title: Mainflux reader service
|
||||
description: HTTP API for reading messages.
|
||||
version: "1.0.0"
|
||||
|
||||
paths:
|
||||
/channels/{chanId}/messages:
|
||||
get:
|
||||
summary: Retrieves messages sent to single channel
|
||||
description: |
|
||||
Retrieves a list of messages sent to specific channel. Due to
|
||||
performance concerns, data is retrieved in subsets. The API readers must
|
||||
ensure that the entire dataset is consumed either by making subsequent
|
||||
requests, or by increasing the subset size of the initial request.
|
||||
tags:
|
||||
- messages
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/Limit"
|
||||
- $ref: "#/components/parameters/Offset"
|
||||
- $ref: "#/components/parameters/ChanId"
|
||||
responses:
|
||||
200:
|
||||
$ref: "#/components/responses/MessagesPageRes"
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
|
||||
components:
|
||||
schemas:
|
||||
MessagesPage:
|
||||
type: object
|
||||
properties:
|
||||
total:
|
||||
type: number
|
||||
description: Total number of items that are present on the system.
|
||||
offset:
|
||||
type: number
|
||||
description: Number of items that were skipped during retrieval.
|
||||
limit:
|
||||
type: number
|
||||
description: Size of the subset that was retrieved.
|
||||
messages:
|
||||
type: array
|
||||
minItems: 0
|
||||
uniqueItems: true
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
channel:
|
||||
type: integer
|
||||
description: Unique channel id.
|
||||
publisher:
|
||||
type: integer
|
||||
description: Unique publisher id.
|
||||
protocol:
|
||||
type: string
|
||||
description: Protocol name.
|
||||
name:
|
||||
type: string
|
||||
description: Measured parameter name.
|
||||
unit:
|
||||
type: string
|
||||
description: Value unit.
|
||||
value:
|
||||
type: number
|
||||
description: Measured value in number.
|
||||
stringValue:
|
||||
type: string
|
||||
description: Measured value in string format.
|
||||
boolValue:
|
||||
type: boolean
|
||||
description: Measured value in boolean format.
|
||||
dataValue:
|
||||
type: string
|
||||
description: Measured value in binary format.
|
||||
valueSum:
|
||||
type: number
|
||||
description: Sum value.
|
||||
time:
|
||||
type: number
|
||||
description: Time of measurement.
|
||||
updateTime:
|
||||
type: number
|
||||
description: Time of updating measurement.
|
||||
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: Thing access token.
|
||||
in: header
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
ChanId:
|
||||
name: chanId
|
||||
description: Unique channel identifier.
|
||||
in: path
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
required: true
|
||||
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
|
||||
|
||||
responses:
|
||||
MessagesPageRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/MessagesPage"
|
||||
|
||||
ServiceError:
|
||||
description: Unexpected server-side error occurred.
|
||||
@@ -1,129 +0,0 @@
|
||||
swagger: "2.0"
|
||||
info:
|
||||
title: Mainflux reader service
|
||||
description: HTTP API for reading messages.
|
||||
version: "1.0.0"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
paths:
|
||||
/channels/{chanId}/messages:
|
||||
get:
|
||||
summary: Retrieves messages sent to single channel
|
||||
description: |
|
||||
Retrieves a list of messages sent to specific channel. Due to
|
||||
performance concerns, data is retrieved in subsets. The API readers must
|
||||
ensure that the entire dataset is consumed either by making subsequent
|
||||
requests, or by increasing the subset size of the initial request.
|
||||
tags:
|
||||
- messages
|
||||
parameters:
|
||||
- $ref: "#/parameters/Authorization"
|
||||
- $ref: "#/parameters/Limit"
|
||||
- $ref: "#/parameters/Offset"
|
||||
- $ref: "#/parameters/ChanId"
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
schema:
|
||||
$ref: "#/definitions/MessagesPage"
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: "#/responses/ServiceError"
|
||||
|
||||
responses:
|
||||
ServiceError:
|
||||
description: Unexpected server-side error occurred.
|
||||
|
||||
definitions:
|
||||
MessagesPage:
|
||||
type: object
|
||||
properties:
|
||||
total:
|
||||
type: number
|
||||
description: Total number of items that are present on the system.
|
||||
offset:
|
||||
type: number
|
||||
description: Number of items that were skipped during retrieval.
|
||||
limit:
|
||||
type: number
|
||||
description: Size of the subset that was retrieved.
|
||||
messages:
|
||||
type: array
|
||||
minItems: 0
|
||||
uniqueItems: true
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
channel:
|
||||
type: integer
|
||||
description: Unique channel id.
|
||||
publisher:
|
||||
type: integer
|
||||
description: Unique publisher id.
|
||||
protocol:
|
||||
type: string
|
||||
description: Protocol name.
|
||||
name:
|
||||
type: string
|
||||
description: Measured parameter name.
|
||||
unit:
|
||||
type: string
|
||||
description: Value unit.
|
||||
value:
|
||||
type: number
|
||||
description: Measured value in number.
|
||||
stringValue:
|
||||
type: string
|
||||
description: Measured value in string format.
|
||||
boolValue:
|
||||
type: boolean
|
||||
description: Measured value in boolean format.
|
||||
dataValue:
|
||||
type: string
|
||||
description: Measured value in binary format.
|
||||
valueSum:
|
||||
type: number
|
||||
description: Sum value.
|
||||
time:
|
||||
type: number
|
||||
description: Time of measurement.
|
||||
updateTime:
|
||||
type: number
|
||||
description: Time of updating measurement.
|
||||
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: Thing access token.
|
||||
in: header
|
||||
type: string
|
||||
required: true
|
||||
ChanId:
|
||||
name: chanId
|
||||
description: Unique channel identifier.
|
||||
in: path
|
||||
type: integer
|
||||
minimum: 1
|
||||
required: true
|
||||
Limit:
|
||||
name: limit
|
||||
description: Size of the subset to retrieve.
|
||||
in: query
|
||||
type: integer
|
||||
default: 10
|
||||
maximum: 100
|
||||
minimum: 1
|
||||
required: false
|
||||
Offset:
|
||||
name: offset
|
||||
description: Number of items to skip during retrieval.
|
||||
in: query
|
||||
type: integer
|
||||
default: 0
|
||||
minimum: 0
|
||||
required: false
|
||||
@@ -15,19 +15,11 @@ paths:
|
||||
- things
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/CreateThingReq"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/ThingCreateReq"
|
||||
responses:
|
||||
201:
|
||||
description: Thing registered.
|
||||
headers:
|
||||
Location:
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
description: Created thing's relative URL.
|
||||
example: /things/{thingId}
|
||||
$ref: "#/components/responses/CreateThingRes"
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
401:
|
||||
@@ -37,7 +29,7 @@ paths:
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
422:
|
||||
description: Database can't process request.
|
||||
description: Database can't process request.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
get:
|
||||
@@ -57,17 +49,13 @@ paths:
|
||||
- $ref: "#/components/parameters/Metadata"
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ThingsPage"
|
||||
$ref: "#/components/responses/ThingsPageRes"
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
401:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: A non-existent entity request.
|
||||
description: A non-existent entity request.
|
||||
422:
|
||||
description: Database can't process request.
|
||||
500:
|
||||
@@ -82,8 +70,8 @@ paths:
|
||||
- things
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/CreateThingsReq"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/ThingsCreateReq"
|
||||
responses:
|
||||
201:
|
||||
description: Things registered.
|
||||
@@ -111,7 +99,7 @@ paths:
|
||||
404:
|
||||
description: Thing does not exist.
|
||||
422:
|
||||
description: Database can't process request.
|
||||
description: Database can't process request.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
put:
|
||||
@@ -126,7 +114,7 @@ paths:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ThingId"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/UpdateThingReq"
|
||||
$ref: "#/components/requestBodies/ThingUpdateReq"
|
||||
responses:
|
||||
200:
|
||||
description: Thing updated.
|
||||
@@ -169,8 +157,8 @@ paths:
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ThingId"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/UpdateKeyReq"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/KeyUpdateReq"
|
||||
responses:
|
||||
200:
|
||||
description: Thing key updated.
|
||||
@@ -196,24 +184,17 @@ paths:
|
||||
- channels
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/CreateChannelReq"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/ChannelCreateReq"
|
||||
responses:
|
||||
201:
|
||||
description: Channel created.
|
||||
headers:
|
||||
Location:
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
description: Created channel's relative URL (i.e. /channels/{chanId}).
|
||||
$ref: "#/components/responses/ChannelCreateRes"
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
401:
|
||||
description: Missing or invalid access token provided.
|
||||
409:
|
||||
description: Entity already exist.
|
||||
description: Entity already exist.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
@@ -234,17 +215,13 @@ paths:
|
||||
- $ref: "#/components/parameters/Name"
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ChannelsPage"
|
||||
$ref: "#/components/responses/ChannelsPageRes"
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
401:
|
||||
description: Missing or invalid access token provided.
|
||||
422:
|
||||
description: Database can't process request.
|
||||
description: Database can't process request.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
/channels/bulk:
|
||||
@@ -257,8 +234,8 @@ paths:
|
||||
- channels
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/CreateChannelsReq"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/ChannelsCreateReq"
|
||||
responses:
|
||||
201:
|
||||
description: Channels registered.
|
||||
@@ -267,7 +244,7 @@ paths:
|
||||
401:
|
||||
description: Missing or invalid access token provided.
|
||||
409:
|
||||
description: Entity already exist.
|
||||
description: Entity already exist.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
@@ -304,8 +281,8 @@ paths:
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- $ref: "#/components/parameters/ChanId"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/CreateChannelReq"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/ChannelCreateReq"
|
||||
responses:
|
||||
200:
|
||||
description: Channel updated.
|
||||
@@ -348,19 +325,11 @@ paths:
|
||||
- things
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/CreateConnectionReq"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/ConnCreateReq"
|
||||
responses:
|
||||
201:
|
||||
description: Thing registered.
|
||||
headers:
|
||||
Location:
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
description: Created thing's relative URL.
|
||||
example: /things/{thingId}
|
||||
$ref: "#/components/responses/ConnCreateRes"
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
401:
|
||||
@@ -368,11 +337,11 @@ paths:
|
||||
404:
|
||||
description: A non-existent entity request.
|
||||
409:
|
||||
description: Entity already exist.
|
||||
description: Entity already exist.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
/things/{thingId}/channels:
|
||||
get:
|
||||
summary: Retrieves list of channels connected or not connected to specified thing
|
||||
@@ -388,11 +357,7 @@ paths:
|
||||
- $ref: "#/components/parameters/Connected"
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ChannelsPage"
|
||||
$ref: "#/components/responses/ChannelsPageRes"
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
401:
|
||||
@@ -418,11 +383,7 @@ paths:
|
||||
- $ref: "#/components/parameters/Connected"
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ThingsPage"
|
||||
$ref: "#/components/responses/ThingsPageRes"
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
401:
|
||||
@@ -430,9 +391,9 @@ paths:
|
||||
404:
|
||||
description: A non-existent entity request.
|
||||
422:
|
||||
description: Database can't process request.
|
||||
description: Database can't process request.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
/channels/{chanId}/things/{thingId}:
|
||||
put:
|
||||
summary: Connects the thing to the channel
|
||||
@@ -449,7 +410,7 @@ paths:
|
||||
200:
|
||||
description: Thing connected.
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
description: Failed due to malformed query parameters.
|
||||
401:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
@@ -471,7 +432,7 @@ paths:
|
||||
204:
|
||||
description: Thing disconnected.
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
description: Failed due to malformed query parameters.
|
||||
401:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
@@ -488,16 +449,11 @@ paths:
|
||||
- access
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/ChanId"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/IdentityReq"
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/IdentityReq"
|
||||
responses:
|
||||
200:
|
||||
description: |
|
||||
Thing has access to the specified channel and the thing ID is returned.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Identity"
|
||||
$ref: "#/components/responses/AccessGrantedRes"
|
||||
401:
|
||||
description: |
|
||||
Thing and channel are not connected, or thing with specified key doesn't
|
||||
@@ -516,7 +472,7 @@ paths:
|
||||
- access
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/ChanId"
|
||||
requestBody:
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/AccessByIDReq"
|
||||
responses:
|
||||
200:
|
||||
@@ -537,23 +493,19 @@ paths:
|
||||
and is valid.
|
||||
tags:
|
||||
- identity
|
||||
requestBody:
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/IdentityReq"
|
||||
responses:
|
||||
200:
|
||||
description: Thing ID returned.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Identity"
|
||||
$ref: "#/components/responses/IdentityRes"
|
||||
401:
|
||||
description: Thing with specified key doesn't exist.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
|
||||
|
||||
$ref: "#/components/responses/ServiceError"
|
||||
|
||||
|
||||
components:
|
||||
schemas:
|
||||
Key:
|
||||
@@ -579,7 +531,7 @@ components:
|
||||
metadata:
|
||||
type: object
|
||||
description: Arbitrary, object-encoded thing's data.
|
||||
ThingResSchema:
|
||||
ThingResSchema:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
@@ -617,7 +569,7 @@ components:
|
||||
type: integer
|
||||
description: Maximum number of items to return in one page.
|
||||
required:
|
||||
- things
|
||||
- things
|
||||
ChannelReqSchema:
|
||||
type: object
|
||||
properties:
|
||||
@@ -626,8 +578,8 @@ components:
|
||||
description: Free-form channel name.
|
||||
metadata:
|
||||
type: object
|
||||
description: Arbitrary, object-encoded channel's data.
|
||||
ChannelResSchema:
|
||||
description: Arbitrary, object-encoded channel's data.
|
||||
ChannelResSchema:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
@@ -668,7 +620,7 @@ components:
|
||||
$ref: "#/components/schemas/Key"
|
||||
channel_ids:
|
||||
type: array
|
||||
description: Channel IDs.
|
||||
description: Channel IDs.
|
||||
items:
|
||||
type: string
|
||||
thing_ids:
|
||||
@@ -689,7 +641,7 @@ components:
|
||||
name: chanId
|
||||
description: Unique channel identifier.
|
||||
in: path
|
||||
schema:
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
ThingId:
|
||||
@@ -704,7 +656,7 @@ components:
|
||||
name: limit
|
||||
description: Size of the subset to retrieve.
|
||||
in: query
|
||||
schema:
|
||||
schema:
|
||||
type: integer
|
||||
default: 10
|
||||
maximum: 100
|
||||
@@ -714,7 +666,7 @@ components:
|
||||
name: offset
|
||||
description: Number of items to skip during retrieval.
|
||||
in: query
|
||||
schema:
|
||||
schema:
|
||||
type: integer
|
||||
default: 0
|
||||
minimum: 0
|
||||
@@ -723,7 +675,7 @@ components:
|
||||
name: connected
|
||||
description: Connection state of the subset to retrieve.
|
||||
in: query
|
||||
schema:
|
||||
schema:
|
||||
type: boolean
|
||||
default: true
|
||||
required: false
|
||||
@@ -731,7 +683,7 @@ components:
|
||||
name: name
|
||||
description: Name filter. Filtering is performed as a case-insensitive partial match.
|
||||
in: query
|
||||
schema:
|
||||
schema:
|
||||
type: string
|
||||
format: byte
|
||||
required: false
|
||||
@@ -745,14 +697,14 @@ components:
|
||||
additionalProperties: {}
|
||||
|
||||
requestBodies:
|
||||
CreateThingReq:
|
||||
ThingCreateReq:
|
||||
description: JSON-formatted document describing the new thing.
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ThingReqSchema"
|
||||
CreateThingsReq:
|
||||
ThingsCreateReq:
|
||||
description: JSON-formatted document describing the new things.
|
||||
required: true
|
||||
content:
|
||||
@@ -761,12 +713,12 @@ components:
|
||||
type: object
|
||||
properties:
|
||||
key:
|
||||
$ref: "#/components/schemas/Key"
|
||||
$ref: "#/components/schemas/Key"
|
||||
things:
|
||||
type: array
|
||||
items:
|
||||
items:
|
||||
$ref: "#/components/schemas/ThingReqSchema"
|
||||
UpdateThingReq:
|
||||
ThingUpdateReq:
|
||||
description: Arbitrary, object-encoded thing's data.
|
||||
required: true
|
||||
content:
|
||||
@@ -779,7 +731,7 @@ components:
|
||||
description: Free-form thing name.
|
||||
metadata:
|
||||
type: object
|
||||
UpdateKeyReq:
|
||||
KeyUpdateReq:
|
||||
required: true
|
||||
description: JSON containing thing.
|
||||
content:
|
||||
@@ -790,28 +742,28 @@ components:
|
||||
key:
|
||||
type: string
|
||||
description: Thing key that is used for thing auth.
|
||||
CreateChannelReq:
|
||||
ChannelCreateReq:
|
||||
description: JSON-formatted document describing the updated channel.
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ChannelReqSchema"
|
||||
CreateChannelsReq:
|
||||
ChannelsCreateReq:
|
||||
description: JSON-formatted document describing the new channels.
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
properties:
|
||||
key:
|
||||
$ref: "#/components/schemas/Key"
|
||||
things:
|
||||
type: array
|
||||
items:
|
||||
items:
|
||||
$ref: "#/components/schemas/ChannelReqSchema"
|
||||
CreateConnectionReq:
|
||||
ConnCreateReq:
|
||||
description: JSON-formatted document describing the new connection.
|
||||
required: true
|
||||
content:
|
||||
@@ -836,7 +788,7 @@ components:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
thing_id:
|
||||
@@ -844,6 +796,72 @@ components:
|
||||
description: Thing ID by which thing is uniquely identified.
|
||||
|
||||
responses:
|
||||
CreateThingRes:
|
||||
description: Thing registered.
|
||||
headers:
|
||||
Location:
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
description: Created thing's relative URL.
|
||||
example: /things/{thingId}
|
||||
ThingRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ThingResSchema"
|
||||
ThingsPageRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ThingsPage"
|
||||
ChannelCreateRes:
|
||||
description: Channel created.
|
||||
headers:
|
||||
Location:
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
description: Created channel's relative URL (i.e. /channels/{chanId}).
|
||||
ChannelRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ChannelResSchema"
|
||||
ChannelsPageRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ChannelsPage"
|
||||
ConnCreateRes:
|
||||
description: Thing registered.
|
||||
headers:
|
||||
Location:
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
description: Created thing's relative URL.
|
||||
example: /things/{thingId}
|
||||
AccessGrantedRes:
|
||||
description: |
|
||||
Thing has access to the specified channel and the thing ID is returned.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Identity"
|
||||
IdentityRes:
|
||||
description: Thing ID returned.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Identity"
|
||||
ServiceError:
|
||||
description: Unexpected server-side error occurred.
|
||||
content:
|
||||
@@ -851,16 +869,3 @@ components:
|
||||
schema:
|
||||
type: string
|
||||
format: byte
|
||||
|
||||
ThingRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ThingResSchema"
|
||||
ChannelRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ChannelResSchema"
|
||||
@@ -0,0 +1,364 @@
|
||||
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
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/Authorization'
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/TwinReq"
|
||||
responses:
|
||||
201:
|
||||
$ref: "#/components/responses/TwinCreateRes"
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: '#/components/responses/ServiceError'
|
||||
|
||||
get:
|
||||
summary: Retrieves managed twins
|
||||
description: |
|
||||
Retrieves a list of managed twins. Due to performance concerns, data
|
||||
is retrieved in subsets.
|
||||
tags:
|
||||
- twins
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/Authorization'
|
||||
- $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.
|
||||
403:
|
||||
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/Authorization'
|
||||
- $ref: '#/components/parameters/TwinID'
|
||||
responses:
|
||||
200:
|
||||
$ref: '#/components/responses/TwinRes'
|
||||
400:
|
||||
description: Failed due to malformed twin's ID.
|
||||
403:
|
||||
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/Authorization'
|
||||
- $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.
|
||||
403:
|
||||
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/Authorization'
|
||||
- $ref: '#/components/parameters/TwinID'
|
||||
responses:
|
||||
204:
|
||||
description: Twin removed.
|
||||
400:
|
||||
description: Failed due to malformed twin's ID.
|
||||
403:
|
||||
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/Authorization'
|
||||
- $ref: '#/components/parameters/Limit'
|
||||
- $ref: '#/components/parameters/Offset'
|
||||
- $ref: '#/components/parameters/Metadata'
|
||||
responses:
|
||||
200:
|
||||
$ref: '#/components/responses/StatesPageRes'
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Twin does not exist.
|
||||
500:
|
||||
$ref: '#/components/responses/ServiceError'
|
||||
|
||||
components:
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: User's access token.
|
||||
in: header
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
@@ -1,343 +0,0 @@
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: Mainflux twins service
|
||||
description: HTTP API for managing digital twins and their states.
|
||||
version: '1.0.0'
|
||||
consumes:
|
||||
- 'application/json'
|
||||
produces:
|
||||
- 'application/json'
|
||||
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
|
||||
parameters:
|
||||
- $ref: '#/parameters/Authorization'
|
||||
- name: twin
|
||||
description: JSON-formatted document describing the new twin.
|
||||
in: body
|
||||
schema:
|
||||
$ref: '#/definitions/TwinReq'
|
||||
required: true
|
||||
responses:
|
||||
201:
|
||||
description: Twin registered.
|
||||
headers:
|
||||
Location:
|
||||
type: string
|
||||
description: Created twin's relative URL (i.e. /twins/{twinID}).
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: '#/responses/ServiceError'
|
||||
|
||||
get:
|
||||
summary: Retrieves managed twins
|
||||
description: |
|
||||
Retrieves a list of managed twins. Due to performance concerns, data
|
||||
is retrieved in subsets.
|
||||
tags:
|
||||
- twins
|
||||
parameters:
|
||||
- $ref: '#/parameters/Authorization'
|
||||
- $ref: '#/parameters/Limit'
|
||||
- $ref: '#/parameters/Offset'
|
||||
- $ref: '#/parameters/Name'
|
||||
- $ref: '#/parameters/Metadata'
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
schema:
|
||||
$ref: '#/definitions/TwinsPage'
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: '#/responses/ServiceError'
|
||||
|
||||
/twins/{twinID}:
|
||||
get:
|
||||
summary: Retrieves twin info
|
||||
tags:
|
||||
- twins
|
||||
parameters:
|
||||
- $ref: '#/parameters/Authorization'
|
||||
- $ref: '#/parameters/TwinID'
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
schema:
|
||||
$ref: '#/definitions/TwinRes'
|
||||
400:
|
||||
description: Failed due to malformed twin's ID.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Twin does not exist.
|
||||
500:
|
||||
$ref: '#/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: '#/parameters/Authorization'
|
||||
- $ref: '#/parameters/TwinID'
|
||||
- name: twin
|
||||
description: JSON-formatted document describing the updated twin.
|
||||
in: body
|
||||
schema:
|
||||
$ref: '#/definitions/TwinReq'
|
||||
required: true
|
||||
responses:
|
||||
200:
|
||||
description: Twin updated.
|
||||
400:
|
||||
description: Failed due to malformed twin's ID or malformed JSON.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Twin does not exist.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
$ref: '#/responses/ServiceError'
|
||||
delete:
|
||||
summary: Removes a twin
|
||||
description: Removes a twin.
|
||||
tags:
|
||||
- twins
|
||||
parameters:
|
||||
- $ref: '#/parameters/Authorization'
|
||||
- $ref: '#/parameters/TwinID'
|
||||
responses:
|
||||
204:
|
||||
description: Twin removed.
|
||||
400:
|
||||
description: Failed due to malformed twin's ID.
|
||||
403:
|
||||
description: Missing or invalid access token provided
|
||||
404:
|
||||
description: Twin does not exist.
|
||||
500:
|
||||
$ref: '#/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: '#/parameters/TwinID'
|
||||
- $ref: '#/parameters/Authorization'
|
||||
- $ref: '#/parameters/Limit'
|
||||
- $ref: '#/parameters/Offset'
|
||||
- $ref: '#/parameters/Metadata'
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
schema:
|
||||
$ref: '#/definitions/StatesPage'
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
404:
|
||||
description: Twin does not exist.
|
||||
500:
|
||||
$ref: '#/responses/ServiceError'
|
||||
|
||||
responses:
|
||||
ServiceError:
|
||||
description: Unexpected server-side error occurred.
|
||||
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
description: User's access token.
|
||||
in: header
|
||||
type: string
|
||||
required: true
|
||||
Limit:
|
||||
name: limit
|
||||
description: Size of the subset to retrieve.
|
||||
in: query
|
||||
type: integer
|
||||
default: 10
|
||||
maximum: 100
|
||||
minimum: 1
|
||||
required: false
|
||||
Offset:
|
||||
name: offset
|
||||
description: Number of items to skip during retrieval.
|
||||
in: query
|
||||
type: integer
|
||||
default: 0
|
||||
minimum: 0
|
||||
required: false
|
||||
Name:
|
||||
name: name
|
||||
description: Twin name
|
||||
in: query
|
||||
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
|
||||
type: string
|
||||
minimum: 0
|
||||
required: false
|
||||
TwinID:
|
||||
name: twinID
|
||||
description: Unique twin identifier.
|
||||
in: path
|
||||
type: string
|
||||
minimum: 1
|
||||
required: true
|
||||
|
||||
definitions:
|
||||
Definition:
|
||||
type: object
|
||||
properties:
|
||||
delta:
|
||||
type: number
|
||||
description: Minimal time delay before new state creation.
|
||||
attributes:
|
||||
type: array
|
||||
minItems: 0
|
||||
uniqueItems: true
|
||||
items:
|
||||
$ref: '#/definitions/Attribute'
|
||||
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.
|
||||
TwinReq:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: Free-form twin name.
|
||||
metadata:
|
||||
type: object
|
||||
description: Arbitrary, object-encoded twin's data.
|
||||
definition:
|
||||
$ref: '#/definitions/Definition'
|
||||
TwinRes:
|
||||
type: object
|
||||
properties:
|
||||
owner:
|
||||
type: string
|
||||
description: Email address of Mainflux user that owns twin.
|
||||
id:
|
||||
type: string
|
||||
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: '#/definitions/Definition'
|
||||
metadata:
|
||||
type: object
|
||||
description: Arbitrary, object-encoded twin's data.
|
||||
TwinsPage:
|
||||
type: object
|
||||
properties:
|
||||
twins:
|
||||
type: array
|
||||
minItems: 0
|
||||
uniqueItems: true
|
||||
items:
|
||||
$ref: '#/definitions/TwinRes'
|
||||
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
|
||||
StateRes:
|
||||
type: object
|
||||
properties:
|
||||
twin_id:
|
||||
type: string
|
||||
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: '#/definitions/StateRes'
|
||||
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
|
||||
@@ -191,7 +191,7 @@ func decodeViewUser(_ context.Context, r *http.Request) (interface{}, error) {
|
||||
func decodeUpdateUser(_ context.Context, r *http.Request) (interface{}, error) {
|
||||
var req updateUserReq
|
||||
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
|
||||
return nil, err
|
||||
return nil, errors.Wrap(users.ErrMalformedEntity, err)
|
||||
}
|
||||
|
||||
req.token = r.Header.Get("Authorization")
|
||||
@@ -376,7 +376,7 @@ func encodeError(_ context.Context, err error, w http.ResponseWriter) {
|
||||
case errors.Contains(errorVal, users.ErrUserNotFound):
|
||||
w.WriteHeader(http.StatusBadRequest)
|
||||
case errors.Contains(errorVal, users.ErrRecoveryToken):
|
||||
w.WriteHeader(http.StatusInternalServerError)
|
||||
w.WriteHeader(http.StatusNotFound)
|
||||
default:
|
||||
w.WriteHeader(http.StatusInternalServerError)
|
||||
}
|
||||
|
||||
@@ -14,18 +14,10 @@ paths:
|
||||
tags:
|
||||
- users
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/CreateUserReq"
|
||||
$ref: "#/components/requestBodies/UserCreateReq"
|
||||
responses:
|
||||
201:
|
||||
description: Registered new user.
|
||||
headers:
|
||||
Location:
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
description: Registred user relative URL
|
||||
example: /users/{userId}
|
||||
$ref: "#/components/responses/UserCreateRes"
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
409:
|
||||
@@ -41,15 +33,11 @@ paths:
|
||||
authorization token
|
||||
tags:
|
||||
- users
|
||||
security:
|
||||
security:
|
||||
- Authorization: []
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserRes"
|
||||
$ref: "#/components/responses/UserRes"
|
||||
400:
|
||||
description: Failed due to malformed query parameters.
|
||||
403:
|
||||
@@ -63,15 +51,17 @@ paths:
|
||||
authorization token and the new received info.
|
||||
tags:
|
||||
- users
|
||||
security:
|
||||
security:
|
||||
- Authorization: []
|
||||
requestBody:
|
||||
$ref: "#/components/requestBodies/UpdateUserReq"
|
||||
$ref: "#/components/requestBodies/UserUpdateReq"
|
||||
responses:
|
||||
200:
|
||||
description: User updated.
|
||||
400:
|
||||
description: Failed due to malformed JSON.
|
||||
404:
|
||||
description: Failed due to non existing user.
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
@@ -79,23 +69,18 @@ paths:
|
||||
/users/{userId}/groups:
|
||||
get:
|
||||
summary: Get groups that user belongs to
|
||||
description: |
|
||||
Retrieves a list of groups that user belongs to.
|
||||
description: Retrieves a list of groups that user belongs to.
|
||||
tags:
|
||||
- users
|
||||
security:
|
||||
security:
|
||||
- Authorization: []
|
||||
parameters:
|
||||
- $ref: "#/parameters/UserID"
|
||||
- $ref: "#/parameters/Offset"
|
||||
- $ref: "#/parameters/Limit"
|
||||
- $ref: "#/components/parameters/UserID"
|
||||
- $ref: "#/components/parameters/Offset"
|
||||
- $ref: "#/components/parameters/Limit"
|
||||
responses:
|
||||
200:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/GroupsPage'
|
||||
$ref: '#/components/responses/GroupsRes'
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
@@ -107,9 +92,9 @@ paths:
|
||||
Create users group.
|
||||
tags:
|
||||
- groups
|
||||
security:
|
||||
security:
|
||||
- Authorization: []
|
||||
requestBody:
|
||||
requestBody:
|
||||
$ref: '#/components/requestBodies/CreateGroupReq'
|
||||
responses:
|
||||
200:
|
||||
@@ -117,18 +102,18 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/GroupsRes'
|
||||
$ref: '#/components/schemas/Group'
|
||||
403:
|
||||
description: Missing or invalid access token provided.
|
||||
500:
|
||||
$ref: '#/components/responses/ServiceError'
|
||||
get:
|
||||
get:
|
||||
summary: Get users groups
|
||||
description: |
|
||||
Get all users groups
|
||||
tags:
|
||||
- groups
|
||||
security:
|
||||
security:
|
||||
- Authorization: []
|
||||
responses:
|
||||
200:
|
||||
@@ -144,11 +129,10 @@ paths:
|
||||
/tokens:
|
||||
post:
|
||||
summary: User authentication
|
||||
description: |
|
||||
Generates an access token when provided with proper credentials.
|
||||
description: Generates an access token when provided with proper credentials.
|
||||
tags:
|
||||
- users
|
||||
security:
|
||||
security:
|
||||
- Authorization: []
|
||||
responses:
|
||||
201:
|
||||
@@ -158,15 +142,13 @@ paths:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Token'
|
||||
400:
|
||||
description: |
|
||||
Failed due to malformed JSON.
|
||||
description: Failed due to malformed JSON.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
403:
|
||||
description: |
|
||||
Failed due to using invalid credentials.
|
||||
description: Failed due to using invalid credentials.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
@@ -183,19 +165,19 @@ paths:
|
||||
post:
|
||||
summary: User password reset request
|
||||
description: |
|
||||
Generates a reset token and sends and email with link for resetting password.
|
||||
Generates a reset token and sends and
|
||||
email with link for resetting password.
|
||||
tags:
|
||||
- users
|
||||
parameters:
|
||||
- $ref: "#/parameters/Referer"
|
||||
- $ref: "#/components/parameters/Referer"
|
||||
requestBody:
|
||||
$ref: '#/components/requestBodies/RequestPasswordReset'
|
||||
responses:
|
||||
201:
|
||||
description: Users link for reseting password.
|
||||
400:
|
||||
description: |
|
||||
Failed due to malformed JSON.
|
||||
description: Failed due to malformed JSON.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
@@ -204,7 +186,9 @@ paths:
|
||||
put:
|
||||
summary: User password reset endpoint
|
||||
description: |
|
||||
When user gets reset token, after he submited email to `/password/reset-request`, posting a new password along to this endpoint will change password.
|
||||
When user gets reset token, after he submited
|
||||
email to `/password/reset-request`, posting a
|
||||
new password along to this endpoint will change password.
|
||||
tags:
|
||||
- users
|
||||
requestBody:
|
||||
@@ -213,8 +197,7 @@ paths:
|
||||
201:
|
||||
description: User link .
|
||||
400:
|
||||
description: |
|
||||
Failed due to malformed JSON.
|
||||
description: Failed due to malformed JSON.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
@@ -226,7 +209,7 @@ paths:
|
||||
When authenticated user wants to change password.
|
||||
tags:
|
||||
- users
|
||||
security:
|
||||
security:
|
||||
- Authorization: []
|
||||
requestBody:
|
||||
$ref: '#/components/requestBodies/PasswordChange'
|
||||
@@ -234,8 +217,7 @@ paths:
|
||||
201:
|
||||
description: User link .
|
||||
400:
|
||||
description: |
|
||||
Failed due to malformed JSON.
|
||||
description: Failed due to malformed JSON.
|
||||
415:
|
||||
description: Missing or invalid content type.
|
||||
500:
|
||||
@@ -247,6 +229,7 @@ components:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
|
||||
schemas:
|
||||
Token:
|
||||
type: object
|
||||
@@ -256,7 +239,7 @@ components:
|
||||
description: Generated access token.
|
||||
required:
|
||||
- token
|
||||
User:
|
||||
UserReqObj:
|
||||
type: object
|
||||
properties:
|
||||
email:
|
||||
@@ -272,7 +255,7 @@ components:
|
||||
required:
|
||||
- email
|
||||
- password
|
||||
Group:
|
||||
GroupReqObj:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
@@ -288,9 +271,9 @@ components:
|
||||
metadata:
|
||||
type: object
|
||||
description: Arbitrary, object-encoded thing's data.
|
||||
required:
|
||||
required:
|
||||
- name
|
||||
UserRes:
|
||||
User:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
@@ -307,7 +290,7 @@ components:
|
||||
type: string
|
||||
format: JSON
|
||||
description: Users metadata
|
||||
GroupsRes:
|
||||
Group:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
@@ -348,7 +331,7 @@ components:
|
||||
minItems: 0
|
||||
uniqueItems: true
|
||||
items:
|
||||
$ref: "#/components/schemas/GroupsRes"
|
||||
$ref: "#/components/schemas/Group"
|
||||
total:
|
||||
type: integer
|
||||
description: Total number of items.
|
||||
@@ -364,19 +347,63 @@ components:
|
||||
error:
|
||||
type: string
|
||||
description: Error message
|
||||
|
||||
|
||||
parameters:
|
||||
Referer:
|
||||
name: Referer
|
||||
description: Host being sent by browser.
|
||||
in: header
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
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
|
||||
UserID:
|
||||
name: userId
|
||||
description: Unique user identifier.
|
||||
in: path
|
||||
schema:
|
||||
type: string
|
||||
format: UUID
|
||||
required: true
|
||||
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
|
||||
|
||||
requestBodies:
|
||||
CreateUserReq:
|
||||
UserCreateReq:
|
||||
description: JSON-formatted document describing the new user to be registered
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
UpdateUserReq:
|
||||
$ref: '#/components/schemas/UserReqObj'
|
||||
UserUpdateReq:
|
||||
description: JSON-formated document describing the metadata of user to be update
|
||||
required: true
|
||||
content:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserMetadata"
|
||||
@@ -386,7 +413,7 @@ components:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Group'
|
||||
$ref: '#/components/schemas/GroupReqObj'
|
||||
RequestPasswordReset:
|
||||
description: Initiate password request procedure.
|
||||
required: true
|
||||
@@ -431,49 +458,30 @@ components:
|
||||
old_password:
|
||||
type: string
|
||||
description: Confirm password
|
||||
|
||||
|
||||
responses:
|
||||
ServiceError:
|
||||
UserCreateRes:
|
||||
description: Registered new user.
|
||||
headers:
|
||||
Location:
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
description: Registred user relative URL
|
||||
example: /users/{userId}
|
||||
UserRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/User"
|
||||
GroupsRes:
|
||||
description: Data retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/GroupsPage'
|
||||
|
||||
ServiceError:
|
||||
description: Unexpected server-side error occurred.
|
||||
|
||||
parameters:
|
||||
Referer:
|
||||
name: Referer
|
||||
description: Host being sent by browser.
|
||||
in: header
|
||||
type: string
|
||||
required: true
|
||||
Metadata:
|
||||
name: metadata
|
||||
description: Metadata filter. Filtering is performed matching the parameter with metadata on top level. Parameter is json.
|
||||
in: query
|
||||
type: string
|
||||
minimum: 0
|
||||
required: false
|
||||
UserID:
|
||||
name: userId
|
||||
description: Unique user identifier.
|
||||
in: path
|
||||
schema:
|
||||
type: string
|
||||
format: UUID
|
||||
required: true
|
||||
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
|
||||
Reference in New Issue
Block a user