Fixes #15956: Move shared-files and remote-run doc to api doc

src/public-api/apidoc.json

@@ -1,21 +1,21 @@
 {
-  "name": "Rudder API documentation",
-  "version": "11.0.0",
-  "description": "Documentation of Rudder server API",
-  "title": "Rudder API documentation",
-  "header": {
-    "title": "",
-    "filename": "src/public-api/introduction.md"
-  },
-  "order": [
-    "Compliance",
-    "Rules",
-    "Directives",
-    "Techniques",
-    "Groups",
-    "Nodes",
-    "Data sources",
-    "Parameters",
-    "Change Requests"
-  ]
-}
+    "name": "Rudder API documentation",
+    "version": "11.0.0",
+    "description": "Documentation of Rudder server API",
+    "title": "Rudder API documentation",
+    "header": {
+        "title": "",
+        "filename": "src/public-api/introduction.md"
+    },
+    "order": [
+        "Compliance",
+        "Rules",
+        "Directives",
+        "Techniques",
+        "Groups",
+        "Nodes",
+        "Data sources",
+        "Parameters",
+        "Change Requests"
+    ]
+}

src/public-api/endpoints/nodes.md

@@ -850,8 +850,6 @@ HTTP/1.1 200 OK
 
       */
 
-
-
 == [POST] api/nodes/{id}/applyPolicy
 
     /**

src/relay-api/apidoc.json

@@ -1,13 +1,15 @@
 {
-  "name": "Rudder relay API documentation",
-  "version": "1.0.0",
-  "description": "Documentation of Rudder relay API",
-  "title": "Rudder relay API documentation",
-  "header": {
-    "title": "",
-    "filename": "src/relay-api/introduction.md"
-  },
-  "order": [
-    "System"
-  ]
-}
+    "name": "Rudder relay API documentation",
+    "version": "1.0.0",
+    "description": "Documentation of Rudder relay API",
+    "title": "Rudder relay API documentation",
+    "header": {
+        "title": "",
+        "filename": "src/relay-api/introduction.md"
+    },
+    "order": [
+        "System",
+        "Remote run",
+        "Shared folder"
+    ]
+}

src/relay-api/endpoints/remoteRun.md

@@ -0,0 +1,93 @@
+This file describes remote-run REST API
+
+ /**
+   @apiDefine nodeId
+
+   @apiParam (URL parameters) {UUID} id ID of the node.
+*/
+
+ /**
+   @apiDefine nodeIds
+
+   @apiParam {UUIDs} ids Comma-separated list of node IDs
+*/
+
+/**
+   @apiDefine keepOutput
+
+   @apiParam {Boolean} [keep_output=false] Forward agent output
+*/
+
+/**
+   @apiDefine asynchronous
+
+   @apiParam {Boolean} [asynchronous=false] Return early or wait for the end of the agent run
+*/
+
+/**
+   @apiDefine conditions
+
+   @apiParam {Conditions} [conditions] Conditions passed as parameter to make it available during agent run, separated by a comma, each condition must match `^[a-zA-Z0-9][a-zA-Z0-9_]*$`
+*/
+
+/**
+   @apiDefine classes
+
+   @apiParam {Conditions} [classes] Deprecated alias for `classes`
+*/
+
+== [POST] api/remote-run/nodes/{id}
+
+    /**
+    @api {post} /api/remote-run/nodes/{id} 1. Trigger a run on a specific node
+    @apiVersion 1.0.0
+    @apiName remoteRunNode
+    @apiGroup Remote run
+
+    @apiUse nodeId
+    @apiUse conditions
+    @apiUse classes
+    @apiUse keepOutput
+    @apiUse asynchronous
+
+    @apiExample Example usage:
+    curl http://localhost:3030/rudder/api/1/remote-run/nodes/2fc7a3a2-4050-4209-afe9-1c5ebc9ce2c8
+
+     */
+
+== [POST] api/remote-run/nodes
+
+    /**
+    @api {post} /api/remote-run/nodes 2. Trigger a run on a list of nodes
+    @apiVersion 1.0.0
+    @apiName remoteRunNodes
+    @apiGroup Remote run
+
+    @apiUse nodeIds
+    @apiUse conditions
+    @apiUse classes
+    @apiUse keepOutput
+    @apiUse asynchronous
+
+    @apiExample Example usage:
+    curl http://localhost:3030/rudder/api/1/remote-run/nodes
+
+     */
+
+== [POST] api/remote-run/nodes/all
+
+    /**
+    @api {post} /api/remote-run/nodes/all 3. Trigger a run on a all nodes managed by target relay
+    @apiVersion 1.0.0
+    @apiName remoteRunNodeAll
+    @apiGroup Remote run
+
+    @apiUse conditions
+    @apiUse classes
+    @apiUse keepOutput
+    @apiUse asynchronous
+
+    @apiExample Example usage:
+    curl http://localhost:3030/rudder/api/1/remote-run/all
+
+     */

src/relay-api/endpoints/sharedFiles.md

@@ -0,0 +1,54 @@
+This file describes shared-files REST API
+
+ /**
+   @apiDefine target_id
+
+   @apiParam (URL parameters) {UUID} target_id ID of the target node
+*/
+
+ /**
+   @apiDefine source_id
+
+   @apiParam (URL parameters) {UUID} source_id ID of the source node
+*/
+
+ /**
+   @apiDefine file_id
+
+   @apiParam (URL parameters) {String} file_id ID of the shared file, must match `[A-z0-9_-.]`
+*/
+
+== [HEAD] api/shared-files/{target_id}/{source_id}/{file_id}
+
+    /**
+    @api {head} /api/shared-files/{target_id}/{source_id}/{file_id} 1. Check if shared file is up to date
+    @apiVersion 1.0.0
+    @apiName sharedFilesHead
+    @apiGroup Shared files
+
+    @apiUse target_id
+    @apiUse source_id
+    @apiUse file_id
+    @apiParam (URL parameters) hash Hash of the target file, used for comparison
+
+    @apiDescription Allows checking if the file needs to be updated. If the file is there and the hash matches, returns a `200`, and a `404` in any other case.
+
+    @apiExample Example usage:
+    curl http://127.0.0.1:3030/rudder/relay-api/1/shared-files/c745a140-40bc-4b86-b6dc-084488fc906b/37817c4d-fbf7-4850-a985-50021f4e8f41/file?hash=c22a3fb1e9de4bfa697ba258f60f14339b72c3faeb043cb75379b9ebcb2717c3
+
+     */
+
+== [PUT] api/shared-files/{target_id}/{source_id}/{file_id}
+
+    /**
+    @api {put} /api/shared-files/{target_id}/{source_id}/{file_id} 2. Share a file with its metadata
+    @apiVersion 1.0.0
+    @apiName sharedFilesPut
+    @apiGroup Shared files
+
+    @apiUse target_id
+    @apiUse source_id
+    @apiUse file_id
+    @apiParam (URL parameters) {TTL} ttl TTL of the file, can be a number of seconds or a duration (in the `1d 2h 3m 4s`, `1d`, etc.) form
+
+     */

src/relay-api/endpoints/sharedFolder.md

@@ -0,0 +1,20 @@
+This file describes shared-folder REST API
+
+== [HEAD] api/shared-folder/{path}/
+
+    /**
+    @api {head} /api/shared-folder/{path} 1. Check file hash in the shared-folder
+    @apiVersion 1.0.0
+    @apiName sharedFolderHash
+    @apiGroup Shared folder
+
+    @apiDescription Allows checking for a file content hash, typically to check if an update is available. If the file hash matches the computed one, a `304` code is returned. If the file exists but does not match the hash (or the hash is absent), a `200` code id returned. Finally, if the file does not exist, a `404` code is returned.
+
+    @apiParam (URL parameters) {Path} path Path of the target file, relative to shared-folder directory
+    @apiParam {Hash} [hash] Hash of the target file
+    @apiParam {HashType} [hash_type=sha256] Hash used, can be `sha256` or `sha512`
+
+    @apiExample Example usage:
+    curl http://localhost:3030/rudder/api/1/shared-folder/myapplication/myfile.conf?hash_type=sha256&hash=181210f8f9c779c26da1d9b2075bde0127302ee0e3fca38c9a83f5b1dd8e5d3b
+
+     */

src/relay-api/endpoints/system.md

@@ -38,7 +38,7 @@ HTTP/1.1 200 OK
     @apiGroup System
 
     @apiExample Example usage:
-    curl http://localhost:3030/rudder/api/latest/system/info
+    curl http://localhost:3030/rudder/api/1/system/info
 
     @apiSuccessExample Success-Response:
 HTTP/1.1 200 OK
@@ -62,11 +62,12 @@ HTTP/1.1 200 OK
     @apiVersion 1.0.0
     @apiName reloadConfiguration
     @apiGroup System
+    @apiDescription Allows to trigger a reload of data files (nodes list, certificates) and logging configuration. Reload is synchronous, and if a success is returned, the reload is already effective.
 
-    @apiExample Example usage (curl):
-     curl -X POST 'http://localhost:3030/rudder/api/1/system/reload'
+    @apiExample Example usage:
+    curl -X POST http://localhost:3030/rudder/api/1/system/reload
 
-    @apiSuccessExample Success Response (curl):
+    @apiSuccessExample Success Response:
 HTTP/1.1 200 OK
 {
   "result": "success",