cleanup > updated hivemq-openapi

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,23 +832,137 @@ 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 '<clientId>' 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\
         \ of the policies with the content-type `application/json`. \n\n This endpoint\
         \ 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