docs(rest.network.configuration.provider): added factory components A…

…PIs to docs (#5000) * docs: added factory components apis to docs Signed-off-by: SimoneFiorani <[email protected]> * Fixed indent layout Signed-off-by: SimoneFiorani <[email protected]> --------- Signed-off-by: SimoneFiorani <[email protected]>
eclipse-kura · Nov 20, 2023 · e8bc998 · e8bc998
1 parent ccc012c
commit e8bc998
Showing 1 changed file with 133 additions and 42 deletions.
diff --git a/docs/references/rest-apis/rest-network-configuration-api.md b/docs/references/rest-apis/rest-network-configuration-api.md
@@ -27,26 +27,26 @@ To access these REST APIs, an identity with `rest.network.configuration` permiss
   * **description** : Returns the list of the available services that manages the network configurations on the system.
   * **responses** :
     * **200**
-      * **description** : The request succeeded.
-      * **response body** :
-        * [PidSet](#pidset)
+        * **description** : The request succeeded.
+        * **response body** :
+            * [PidSet](#pidset)
     * **500**
-      * **description** : An unexpected internal error occurred.
-      * **response body** :
-        * [GenericFailureReport](#genericfailurereport)
+        * **description** : An unexpected internal error occurred.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
 
 #### GET/configurableComponents/configurations
   * **REST API path** : `/services/networkConfiguration/v1/configurableComponents/configurations`
   * **description** : Returns all of network component configurations available on the system. This request will return the `pid`, `ocd` and `properties`.
   * **responses** :
     * **200**
-      * **description** : The request succeeded.
-      * **response body** :
-        * [ComponentConfigurationList](#componentconfigurationlist)
+        * **description** : The request succeeded.
+        * **response body** :
+            * [ComponentConfigurationList](#componentconfigurationlist)
     * **500**
-      * **description** : An unexpected internal error occurred.
-      * **response body** :
-        * [GenericFailureReport](#genericfailurereport)
+        * **description** : An unexpected internal error occurred.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
 
 #### POST/configurableComponents/configurations/byPid
   * **REST API path** : `/services/networkConfiguration/v1/configurableComponents/configurations/byPid`
@@ -55,17 +55,17 @@ To access these REST APIs, an identity with `rest.network.configuration` permiss
     * [PidSet](#pidset)
   * **responses** :
     * **200**
-      * **description** : The request succeeded. If the network configuration for a given pid cannot be found, it will not be included in the result.
-      * **response body** :
-        * [ComponentConfigurationList](#componentconfigurationlist)
+        * **description** : The request succeeded. If the network configuration for a given pid cannot be found, it will not be included in the result.
+        * **response body** :
+            * [ComponentConfigurationList](#componentconfigurationlist)
     * **400**
-      * **description** : The request body is not valid JSON or it contains invalid parameters.
-      * **response body** :
-        * [GenericFailureReport](#genericfailurereport)
+        * **description** : The request body is not valid JSON or it contains invalid parameters.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
     * **500**
-      * **description** : An unexpected internal error occurred.
-      * **response body** :
-        * [GenericFailureReport](#genericfailurereport)
+        * **description** : An unexpected internal error occurred.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
 
 #### POST/configurableComponents/configurations/byPid/_default
   * **REST API path** : `/services/networkConfiguration/v1/configurableComponents/configurations/byPid/_default`
@@ -74,17 +74,17 @@ To access these REST APIs, an identity with `rest.network.configuration` permiss
     * [PidSet](#pidset)
   * **responses** :
     * **200**
-      * **description** : The request succeeded. If the network configuration for a given pid cannot be found, it will not be included in the result.
-      * **response body** :
-        * [ComponentConfigurationList](#componentconfigurationlist)
+        * **description** : The request succeeded. If the network configuration for a given pid cannot be found, it will not be included in the result.
+        * **response body** :
+            * [ComponentConfigurationList](#componentconfigurationlist)
     * **400**
-      * **description** : The request body is not valid JSON or it contains invalid parameters.
-      * **response body** :
-        * [GenericFailureReport](#genericfailurereport)
+        * **description** : The request body is not valid JSON or it contains invalid parameters.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
     * **500**
-      * **description** : An unexpected internal error occurred.
-      * **response body** :
-        * [GenericFailureReport](#genericfailurereport)
+        * **description** : An unexpected internal error occurred.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
 
 #### PUT/configurableComponents/configurations/_update
   * **REST API path** : `/services/networkConfiguration/v1/configurableComponents/configurations/_update`
@@ -93,21 +93,112 @@ To access these REST APIs, an identity with `rest.network.configuration` permiss
     * [UpdateComponentConfigurationRequest](#updatecomponentconfigurationrequest)
   * **responses** :
     * **200**
-      * **description** : The request succeeded.
+        * **description** : The request succeeded.
+    * **400**
+        * **description** : The request body is not valid JSON or it contains invalid parameters.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
+    * **500**
+        * **description** : In case of processing errors, the device will attempt to return a detailed error response containing a message describing the failure reason for each operation. The operation ids are the following: `update:$pid` for component update operations, where `$pid` is the pid of the instance, and `snapshot`, for the snapshot creation operation. In case of an unexpected failure, a generic error response will be returned.
+        * **response body** :
+            * **Variants**:
+                * **object**
+                    * [GenericFailureReport](#genericfailurereport)
+                * **object**
+                    * [BatchFailureReport](#batchfailurereport)
+
+!!! warning
+    `factoryComponents` endopoints are available in the current version of Kura for future compatibility. Currently, as of Kura 5.4.0, there are no network related components that are factory components.
+
+    The endopoints that should return a list of pids will always return an empty array, while those that should create, delete or update a component will always return a 500 error.
+
+#### GET/factoryComponents
+  * **REST API path** : `/services/networkConfiguration/v1/factoryComponents`
+  * **description** : Returns the ids of the network component factories available on the device.
+  * **responses** :
+    * **200**
+        * **description** : The factory pid set.
+        * **response body** :
+            * [PidSet](#pidset)
+    * **500**
+        * **description** : An unexpected internal error occurred.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
+
+#### POST/factoryComponents
+  * **REST API path** : `/services/networkConfiguration/v1/factoryComponents`
+  * **description** : This is a batch request that allows to create one or more network factory component instances and optionally create a new snapshot.
+  * **request body** :
+    * [CreateFactoryComponentConfigurationsRequest](../../core-services/configuration-service-rest-v2.md#createfactorycomponentconfigurationsrequest)
+  * **responses** :
+    * **200**
+        * **description** : The request succeeded.
+    * **400**
+        * **description** : The request body is not valid JSON or it contains invalid parameters.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
+    * **500**
+          * **description** : In case of processing errors, the device will attempt to return a detailed error response containing a message describing the failure reason for each operation. The operation ids are the following: `create:$pid` for component creation operations, where `$pid` is the pid of the instance, and `snapshot`, for the snapshot creation operation. In case of an unexpected failure, a generic error response will be returned.
+
+        * **response body** :
+            * **Variants**:  
+                * **object**
+                    * [GenericFailureReport](#genericfailurereport)
+                * **object**
+                    * [BatchFailureReport](#batchfailurereport)
+
+#### DEL/factoryComponents/byPid
+  * **REST API path** : `/services/networkConfiguration/v1/factoryComponents/byPid`
+  * **description** : This is a batch request that allows to delete one or more network factory component instances and optionally create a new snapshot.
+  * **request body** :
+    * [DeleteFactoryComponentConfigurationsRequest](../../core-services/configuration-service-rest-v2.md#deletefactorycomponentconfigurationsrequest)
+  * **responses** :
+    * **200**
+        * **description** : The request succeeded.
     * **400**
-      * **description** : The request body is not valid JSON or it contains invalid parameters.
-      * **response body** :
-        * [GenericFailureReport](#genericfailurereport)
+        * **description** : The request body is not valid JSON or it contains invalid parameters.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
+    * **500**
+        * **description** : In case of processing errors, the device will attempt to return a detailed error response containing a message describing the failure reason for each operation. The operation ids are the following: `delete:$pid` for component delete operations, where `$pid` is the pid of the instance, and `snapshot`, for the snapshot creation operation. In case of an unexpected failure, a generic error response will be returned.
+          * **response body** :
+            * **Variants**:
+                * **object**
+                    * [GenericFailureReport](#genericfailurereport)
+                * **object**
+                    * [BatchFailureReport](#batchfailurereport)
+
+#### GET/factoryComponents/ocd
+  * **REST API path** : `/services/networkConfiguration/v1/factoryComponents/ocd`
+  * **description** : Returns the OCD of the network components created by the factories available on the device without the need of creating an instance. This request returns the information related to all available network factories.
+  * **responses** :
+    * **200**
+        * **description** : The request succeeded. The `pid` property of the received configurations will report the factory pid, the `ocd` field will contain the definition, the `properties` field will not be present.
+        * **response body** :
+            * [ComponentConfigurationList](#componentconfigurationlist)
+    * **500**
+        * **description** : An unexpected internal error occurred.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
+
+#### POST/factoryComponents/ocd/byFactoryPid
+  * **REST API path** : `/services/networkConfiguration/v1/factoryComponents/ocd/byFactoryPid`
+  * **description** : Returns the OCD of the components created by the factories available on the device without the need of creating an instance. This request returns the information related to a user selected set of factories.
+  * **request body** :
+    * [PidSet](#pidset)
+  * **responses** :
+    * **200**
+        * **description** : The request succeeded. The `pid` property of the received configurations will report the factory pid, the `ocd` field will contain the definition, the `properties` field will not be present. If the OCD for a given factory pid cannot be found, it will not be included in the result.
+        * **response body** :
+            * [ComponentConfigurationList](#componentconfigurationlist)
+    * **400**
+        * **description** : The request body is not valid JSON or it contains invalid parameters.
+        * **response body** :
+            * [GenericFailureReport](#genericfailurereport)
     * **500**
-      * **description** : In case of processing errors, the device will attempt to return a detailed error response containing a message describing the failure reason for each operation. The operation ids are the following: `update:$pid` for component update operations, where `$pid` is the pid of the instance, and `snapshot`, for the snapshot creation operation. In case of an unexpected failure, a generic error response will be returned.
-      * **response body** :
-
-        **Variants**:
-
-          * **object**
+        * **description** : An unexpected internal error occurred.
+        * **response body** :
             * [GenericFailureReport](#genericfailurereport)
-          * **object**
-            * [BatchFailureReport](#batchfailurereport)
 
 
 ## JSON definitions