mirror of
https://github.com/absmach/magistrala.git
synced 2026-06-23 04:10:28 +00:00
Dušan Borovčanin
ef5c253c51
Signed-off-by: nyagamunene <stevenyaga2014@gmail.com> Signed-off-by: dusan <borovcanindusan1@gmail.com> Co-authored-by: Steve Munene <stevenyaga2014@gmail.com>
700 lines
21 KiB
YAML
700 lines
21 KiB
YAML
# Copyright (c) Abstract Machines
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
|
|
openapi: 3.0.1
|
|
info:
|
|
title: Magistrala Bootstrap service
|
|
description: |
|
|
HTTP API for managing platform clients configuration.
|
|
Some useful links:
|
|
- [The Magistrala repository](https://github.com/absmach/supermq)
|
|
contact:
|
|
email: info@absmach.eu
|
|
license:
|
|
name: Apache 2.0
|
|
url: https://github.com/absmach/supermq/blob/main/LICENSE
|
|
version: 0.18.5
|
|
|
|
servers:
|
|
- url: http://localhost:9013
|
|
- url: https://localhost:9013
|
|
|
|
tags:
|
|
- name: configs
|
|
description: Everything about your Configs
|
|
externalDocs:
|
|
description: Find out more about Configs
|
|
url: https://docs.magistrala.absmach.eu
|
|
|
|
paths:
|
|
/{domainID}/clients/configs:
|
|
post:
|
|
operationId: createConfig
|
|
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/DomainID"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/ConfigCreateReq"
|
|
responses:
|
|
"201":
|
|
$ref: "#/components/responses/ConfigCreateRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"404":
|
|
description: A non-existent entity request.
|
|
"409":
|
|
description: Failed due to using an existing identity.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
"503":
|
|
description: Failed to receive response from the clients service.
|
|
get:
|
|
operationId: getConfigs
|
|
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/DomainID"
|
|
- $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.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/{domainID}/clients/configs/{configID}:
|
|
get:
|
|
operationId: getConfig
|
|
summary: Retrieves config info (with channels).
|
|
tags:
|
|
- configs
|
|
parameters:
|
|
- $ref: "#/components/parameters/DomainID"
|
|
- $ref: "#/components/parameters/ConfigId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/ConfigRes"
|
|
"400":
|
|
description: Missing or invalid config.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"404":
|
|
description: Config does not exist.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
put:
|
|
operationId: updateConfig
|
|
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, SuperMQ Client ID and key cannot be changed.
|
|
tags:
|
|
- configs
|
|
parameters:
|
|
- $ref: "#/components/parameters/DomainID"
|
|
- $ref: "#/components/parameters/ConfigId"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/ConfigUpdateReq"
|
|
responses:
|
|
"200":
|
|
description: Config updated.
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"404":
|
|
description: Config does not exist.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
delete:
|
|
operationId: removeConfig
|
|
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 SuperMQ channels.
|
|
tags:
|
|
- configs
|
|
parameters:
|
|
- $ref: "#/components/parameters/DomainID"
|
|
- $ref: "#/components/parameters/ConfigId"
|
|
responses:
|
|
"204":
|
|
description: Config removed.
|
|
"400":
|
|
description: Failed due to malformed config ID.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/{domainID}/clients/configs/certs/{configID}:
|
|
patch:
|
|
operationId: updateConfigCerts
|
|
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/DomainID"
|
|
- $ref: "#/components/parameters/ConfigId"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/ConfigCertUpdateReq"
|
|
responses:
|
|
"200":
|
|
description: Config updated.
|
|
$ref: "#/components/responses/ConfigUpdateCertsRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"404":
|
|
description: Config does not exist.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/{domainID}/clients/configs/connections/{configID}:
|
|
put:
|
|
operationId: updateConfigConnections
|
|
summary: Updates channels the client is connected to
|
|
description: |
|
|
Update connections performs update of the channel list corresponding
|
|
Client is connected to.
|
|
tags:
|
|
- configs
|
|
parameters:
|
|
- $ref: "#/components/parameters/DomainID"
|
|
- $ref: "#/components/parameters/ConfigId"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/ConfigConnUpdateReq"
|
|
responses:
|
|
"200":
|
|
description: Config updated.
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"404":
|
|
description: Config does not exist.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/clients/bootstrap/{externalId}:
|
|
get:
|
|
operationId: getBootstrapConfig
|
|
summary: Retrieves configuration.
|
|
description: |
|
|
Retrieves a configuration with given external ID and external key.
|
|
tags:
|
|
- configs
|
|
security:
|
|
- bootstrapAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/ExternalId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/BootstrapConfigRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"401":
|
|
description: Missing or invalid external key provided.
|
|
"404":
|
|
description: Failed to retrieve corresponding config.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/clients/bootstrap/secure/{externalId}:
|
|
get:
|
|
operationId: getSecureBootstrapConfig
|
|
summary: Retrieves configuration.
|
|
description: |
|
|
Retrieves a configuration with given external ID and encrypted external key.
|
|
tags:
|
|
- configs
|
|
security:
|
|
- bootstrapEncAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/ExternalId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/BootstrapConfigRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"404":
|
|
description: |
|
|
Failed to retrieve corresponding config.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/{domainID}/clients/state/{configID}:
|
|
put:
|
|
operationId: updateConfigState
|
|
summary: Updates Config state.
|
|
description: |
|
|
Updating state represents enabling/disabling Config, i.e. connecting
|
|
and disconnecting corresponding SuperMQ Client to the list of Channels.
|
|
tags:
|
|
- configs
|
|
parameters:
|
|
- $ref: "#/components/parameters/DomainID"
|
|
- $ref: "#/components/parameters/ConfigId"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/ConfigStateUpdateReq"
|
|
responses:
|
|
"204":
|
|
description: Config removed.
|
|
"400":
|
|
description: Failed due to malformed config's ID.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"404":
|
|
description: A non-existent entity request.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/health:
|
|
get:
|
|
summary: Retrieves service health check info.
|
|
tags:
|
|
- health
|
|
security: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/HealthRes"
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
components:
|
|
schemas:
|
|
State:
|
|
type: integer
|
|
enum: [0, 1]
|
|
Config:
|
|
type: object
|
|
properties:
|
|
client_id:
|
|
type: string
|
|
format: uuid
|
|
description: Corresponding SuperMQ Client ID.
|
|
magistrala_secret:
|
|
type: string
|
|
format: uuid
|
|
description: Corresponding SuperMQ Client key.
|
|
channels:
|
|
type: array
|
|
minItems: 0
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: Channel unique identifier.
|
|
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"
|
|
client_cert:
|
|
type: string
|
|
description: Client certificate.
|
|
ca_cert:
|
|
type: string
|
|
description: Issuing CA certificate.
|
|
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:
|
|
client_id:
|
|
type: string
|
|
format: uuid
|
|
description: Corresponding SuperMQ Client ID.
|
|
client_key:
|
|
type: string
|
|
format: uuid
|
|
description: Corresponding SuperMQ Client key.
|
|
channels:
|
|
type: array
|
|
minItems: 0
|
|
items:
|
|
type: string
|
|
content:
|
|
type: string
|
|
description: Free-form custom configuration.
|
|
client_cert:
|
|
type: string
|
|
description: Client certificate.
|
|
required:
|
|
- client_id
|
|
- client_key
|
|
- channels
|
|
- content
|
|
ConfigUpdateCerts:
|
|
type: object
|
|
properties:
|
|
client_id:
|
|
type: string
|
|
format: uuid
|
|
description: Corresponding SuperMQ Client ID.
|
|
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:
|
|
- client_id
|
|
- client_key
|
|
- channels
|
|
- content
|
|
|
|
parameters:
|
|
ConfigId:
|
|
name: configID
|
|
description: Unique Config identifier. It's the ID of the corresponding Client.
|
|
in: path
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
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
|
|
DomainID:
|
|
name: domainID
|
|
description: Unique domain identifier.
|
|
in: path
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: true
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
|
|
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.
|
|
client_id:
|
|
type: string
|
|
format: uuid
|
|
description: ID of the corresponding SuperMQ Client.
|
|
channels:
|
|
type: array
|
|
minItems: 0
|
|
items:
|
|
type: string
|
|
format: uuid
|
|
content:
|
|
type: string
|
|
name:
|
|
type: string
|
|
client_cert:
|
|
type: string
|
|
description: Client Certificate.
|
|
client_key:
|
|
type: string
|
|
description: Client Private Key.
|
|
ca_cert:
|
|
type: string
|
|
required:
|
|
- external_id
|
|
- external_key
|
|
ConfigUpdateReq:
|
|
description: JSON-formatted document describing the updated client.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
content:
|
|
type: string
|
|
name:
|
|
type: string
|
|
required:
|
|
- content
|
|
- name
|
|
ConfigCertUpdateReq:
|
|
description: JSON-formatted document describing the updated client.
|
|
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 client is be connected to.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
channels:
|
|
type: array
|
|
minItems: 0
|
|
items:
|
|
type: string
|
|
format: uuid
|
|
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. /clients/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"
|
|
links:
|
|
update:
|
|
operationId: updateConfig
|
|
parameters:
|
|
configID: $response.body#/id
|
|
updateCerts:
|
|
operationId: updateConfigCerts
|
|
parameters:
|
|
configID: $response.body#/id
|
|
updateConnections:
|
|
operationId: updateConfigConnections
|
|
parameters:
|
|
configID: $response.body#/id
|
|
updateState:
|
|
operationId: updateConfigState
|
|
parameters:
|
|
configID: $response.body#/id
|
|
delete:
|
|
operationId: removeConfig
|
|
parameters:
|
|
configID: $response.body#/id
|
|
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.
|
|
HealthRes:
|
|
description: Service Health Check.
|
|
content:
|
|
application/health+json:
|
|
schema:
|
|
$ref: "./schemas/health_info.yaml"
|
|
ConfigUpdateCertsRes:
|
|
description: Data retrieved. Config certs updated.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ConfigUpdateCerts"
|
|
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
* Users access: "Authorization: Bearer <user_token>"
|
|
|
|
bootstrapAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: string
|
|
description: |
|
|
* Clients access: "Authorization: Client <external_key>"
|
|
|
|
bootstrapEncAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: aes-sha256-uuid
|
|
description: |
|
|
* Clients access: "Authorization: Client <external_enc_key>"
|
|
Hex-encoded configuration external key encrypted using
|
|
the AES algorithm and SHA256 sum of the external key
|
|
itself as an encryption key.
|
|
|
|
security:
|
|
- bearerAuth: []
|