diff --git a/specs/hivemq-openapi.yaml b/specs/hivemq-openapi.yaml index d5f05694f..618330a98 100644 --- a/specs/hivemq-openapi.yaml +++ b/specs/hivemq-openapi.yaml @@ -82,7 +82,7 @@ info: x-logo: url: https://www.hivemq.com/img/svg/hivemq-bee.svg tags: -- description: |- + - description: |- These endpoints can be used to manage the Data Hub. Currently, this includes the option to start a 5-hour long trial mode that temporarily removes all limitations.For more information on all capabilities the HiveMQ Data Hub offers, see the [HiveMQ documentation](https://docs.hivemq.com/hivemq/latest/data-hub/index.html). @@ -126,6 +126,10 @@ tags: For more information on how to define and use a schema in HiveMQ, see [Schemas](https://docs.hivemq.com/hivemq/latest/data-hub/schemas.html). name: Data Hub - Schemas +- description: |+ + These endpoints can be used to retrieve states of clients for the Data Hub. + + name: Data Hub - State - description: |- These endpoints can be used to create, download, inspect and restore backups created by HiveMQ. @@ -828,15 +832,129 @@ paths: summary: Version check failed value: errors: - - title: Endpoint not active yet - detail: "Not all cluster nodes support this endpoint yet, please\ + - title: Endpoint not active yet + detail: "Not all cluster nodes support this endpoint yet, please\ \ try again later" schema: $ref: '#/components/schemas/Errors' description: Not all cluster nodes at minimum version summary: Update an existing policy tags: - - Data Hub - Behavior Policies + - Data Hub - Behavior Policies + /api/v1/data-hub/behavior-validation/states/{clientId}: + get: + description: |- + Use this endpoint to get the stored state of a client for DataHub. + + This endpoint requires at least HiveMQ version 4.20.0 on the REST API node. + operationId: getClientState + parameters: + - description: The client identifier. + example: client1 + in: path + name: clientId + required: true + schema: + type: string + example: null + responses: + "200": + content: + application/json: + examples: + get-response: + description: Get client State + summary: Get the state of a client + value: + items: + - policyId: reallyCoolBehaviorPolicy + behaviorId: Publish.quota + stateType: INTERMEDIATE + stateName: Connected + firstSetAt: 2023-09-05T09:46:47.854Z + arguments: + MinAmountOfPublishes: 5 + MaxAmountOfPublishes: 10 + variables: + MinAmountOfPublishes: "5" + PublishCount: "0" + MaxAmountOfPublishes: "10" + schema: + $ref: '#/components/schemas/FsmStatesInformationListItem' + description: Success + "400": + content: + application/json: + examples: + param-missing: + description: Bad request + summary: Required URL parameter missing + value: + errors: + - title: Required parameter missing + detail: Required URL parameter 'parameterName' is missing + schema: + $ref: '#/components/schemas/Errors' + description: Bad request + "404": + content: + application/json: + examples: + client-disconnected: + description: Example response when client is disconnected + summary: "Target client is not connected at the moment, but a session\ + \ is present." + value: |- + { + "errors": [ + { + "title": "Client disconnected + "detail": "The client 'client' is disconnected." + } + ] + } + client-not-found: + description: Example response when client identifier is unknown + to the broker + summary: "Target client is not known to the broker, because there\ + \ is no session present." + value: |- + { + "errors": [ + { + "title": "Client not found + "detail": "The client '' was not found." + } + ] + } + not-found: + description: Resource not found + summary: Not found + value: + errors: + - title: Resource not found + detail: Resource with id 'my-resource-id' not found + schema: + $ref: '#/components/schemas/Errors' + description: Resource not found + "503": + content: + application/json: + examples: + temporarily-not-available: + description: The endpoint is temporarily not available + summary: Temporarily not available + value: + errors: + - title: The endpoint is temporarily not available + detail: "The endpoint is temporarily not available, please try\ + \ again later" + schema: + $ref: '#/components/schemas/Errors' + description: Temporarily not available + summary: Get the state of a client + tags: + - Data Hub - State /api/v1/data-hub/data-validation/policies: get: description: "Get all data policies. \n\n This endpoint returns the content\ @@ -844,7 +962,7 @@ paths: \ requires at least HiveMQ version 4.15.0 on all cluster nodes." operationId: getAllDataPolicies parameters: - - description: "Comma-separated list of fields to include in the response. Allowed\ + - description: "Comma-separated list of fields to include in the response. Allowed\ \ values are: id, createdAt, lastUpdatedAt, matching, validation, onSuccess,\ \ onFailure" example: "id,createdAt" @@ -3837,6 +3955,55 @@ components: example: null items: $ref: '#/components/schemas/Error' + FsmStateInformationItem: + type: object + description: List of result items that are returned by this endpoint + example: null + properties: + arguments: + $ref: '#/components/schemas/JsonNode' + behaviorId: + type: string + description: The unique identifier of the policy. + example: null + firstSetAt: + type: string + description: The timestamp when this state was set the first time. + example: null + policyId: + type: string + description: The unique identifier of the policy. + example: null + stateName: + type: string + description: The name of the fsm state. + example: null + stateType: + type: string + description: The type of the fsm state. + example: null + variables: + type: object + additionalProperties: + type: string + description: The variables for this fsm. + example: null + description: The variables for this fsm. + example: null + FsmStatesInformationListItem: + type: object + example: null + properties: + items: + type: array + description: List of result items that are returned by this endpoint + example: null + items: + $ref: '#/components/schemas/FsmStateInformationItem' + JsonNode: + type: object + description: The arguments of the fsm derived from the behavior policy. + example: null PaginationCursor: type: object description: Links for pagination