docs: Added Service Listing rest api documentation (#4861)

* Added Service Listing rest api documentation Signed-off-by: SimoneFiorani <[email protected]> * Removed <sorted> word from endopoints Signed-off-by: SimoneFiorani <[email protected]> --------- Signed-off-by: SimoneFiorani <[email protected]>
eclipse-kura · Sep 20, 2023 · 5685a5a · 5685a5a
1 parent 8c830af
commit 5685a5a
Show file tree

Hide file tree

Showing 2 changed files with 145 additions and 0 deletions.
diff --git a/docs/references/rest-apis/rest-service-listing-api.md b/docs/references/rest-apis/rest-service-listing-api.md
@@ -0,0 +1,144 @@
+!!! note
+
+    This API can also be accessed via the RequestHandler with app-id: `SVCLIST-V1`.
+
+#### Get Service List
+- Method: GET
+- API PATH: `/services/serviceListing/v1/list`
+
+##### Responses
+- 200 OK status
+
+```JSON
+{
+	//Alphabetically ordered list of services running on kura
+    "servicesList": [
+        "HttpsKeystore",
+        ...
+        ...
+        "org.eclipse.kura.clock.ClockService",
+        ...
+        ...
+        "org.eclipse.kura.data.DataService",
+        ...
+        ...
+    ]
+}
+```
+
+---
+#### Get Service List filtereb by interfaces 
+- Method: POST
+- API PATH: `/services/serviceListing/v1/list/byInterface`
+
+##### Responses
+- 200 OK status
+
+```JSON
+Filter example
+
+{
+  "interfacesIds": [
+    "org.eclipse.kura.security.keystore.KeystoreService"
+  ]
+}
+
+```
+
+```JSON
+{
+    //Alphabetically ordered list of services running on kura filtered by implemented interfaces
+	"servicesList": [
+        "HttpsKeystore",
+        "SSLKeystore"
+    ]
+}
+```
+
+If more than one interface is present in the `interfaceIds` request body, a logic AND of those are performed.
+Example:
+
+```JSON
+Filter example
+
+{
+  "interfacesIds": [
+    "org.eclipse.kura.configuration.ConfigurableComponent",
+    "org.eclipse.kura.watchdog.WatchdogService"
+  ]
+}
+```
+```JSON
+Response:
+{
+    "servicesList": [
+        "org.eclipse.kura.watchdog.WatchdogService"
+    ]
+}
+```
+
+- 500 Internal Server Error
+    - Can occur if body json is not correctly written
+```JSON
+    Example:
+
+    {
+        "interfacesIds": 
+    }
+```
+
+- 400 Bad Status
+    - If body json is null
+    ```JSON
+    Body:
+    {
+    }
+
+    Response:
+    {
+        "message": "Bad request. interfacesIds must not be null"
+    }
+    ```
+    - If body json is empty
+    ```JSON
+    Body:
+    {
+        "interfacesIds": [
+        ]
+    }
+
+    Response:
+    {
+        "message": "Bad request. interfacesIds must not be empty"
+    }
+    ```
+    - If body json contains null entry
+    ```JSON
+    Body:
+    {
+        "interfacesIds": [
+            "org.eclipse.kura.configuration.ComponentConfiguration",
+
+        ]
+    }
+
+    Response:
+    {
+        "message": "Bad request. none of the interfacesIds can be null"
+    }
+    ```
+    - If body json contains empty entry
+    ```JSON
+    Body:
+    {
+        "interfacesIds": [
+            "org.eclipse.kura.configuration.ComponentConfiguration",
+            ""
+        ]
+    }
+
+    Response:
+    {
+        "message": "Bad request. none of the interfacesIds can be null"
+    }
+    ```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -152,6 +152,7 @@ nav:
         - Inventory: references/rest-apis/rest-inventory-api.md
         - Position: references/rest-apis/rest-position-api.md
         - Security: references/rest-apis/rest-security-api.md
+        - Service Listing: references/rest-apis/rest-service-listing-api.md
         - Session: references/rest-apis/rest-session-api.md
         - System: references/rest-apis/rest-system-api.md
     - Tutorials: