Fixes #15962: Complete shared-files documentation with the metadata f…

…ormat

src/relay-api/endpoints/sharedFiles.md

@@ -29,9 +29,9 @@ This file describes shared-files REST API
     @apiUse target_id
     @apiUse source_id
     @apiUse file_id
-    @apiParam (URL parameters) hash Hash of the target file, used for comparison
+    @apiParam (URL parameters) {Hash} 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.
+    @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 cases.
 
     @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
@@ -49,6 +49,18 @@ This file describes shared-files REST API
     @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
+    @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`, `1 day`, `3 hours`, etc.) form
+
+    @apiParam (Metadata parameters) {Version} header Version of the metadata, for now always `rudder-signature-v1`
+    @apiParam (Metadata parameters) {HashType} algorithm Can be `sha256` or `sha512`
+    @apiParam (Metadata parameters) {Disgest} digest Signature of the file (can be obtained with `openssl dgst -passin "pass:${PASSPHRASE}" -sha512 -hex -sign "${PRIVKEY}" < "${FILE}"`)
+    @apiParam (Metadata parameters) {Hash} hash_value Hash of the file, using the chosen hash type
+    @apiParam (Metadata parameters) {HashType} short_pubkey Agent's public key, matching the key used to sign the file
+    @apiParam (Metadata parameters) {Hostname} hostname Source node's hostname
+    @apiParam (Metadata parameters) {Date} keydate Formatted date, `yyyy-mm-dd HH:mm:ss.ms +XXXX` where XXXX stands for the four timezone digits, according to RFC 822.
+    @apiParam (Metadata parameters) {Id} keyid Public key identifier (last 4 bytes of the modulus)
+
+    @apiDescription Allow shared a file, along with metadata and a ttl. The request body a the concatenation
+    of the metadata (containing the signature) with the file content, separated by en empty line. The receiving relay will either directly share it if the target node is a sub node, or forward the request to the appropriate relay (sub relay or upstream depending if it is under the current relay or not).
 
      */

src/relay-api/introduction.md

@@ -1,16 +1,16 @@
 # Introduction
 
-Rudder relay exposes an internal REST API, enabling the agents and other services to interact with the relay.
+Rudder relay exposes an internal API, enabling the agents and other services to interact with the relay.
 
 <span id="api-_-Authentication"/>
 
 ## Authentication
 
-The relay API are in general not authentified, and it is done on a case-by-case basis:
+The relay API are in general not authenticated, and it is done on a case-by-case basis:
 
 * remote-run is only accessible to request with the IP of the policy server
 * shared-files checks file signature based on known public keys from nodes
-* system API is only accessible to local clients and do not permit acess to
+* system API is only accessible to local clients and do not permit access to
   private information not modification abilities
 
 <span id="api-_-Versioning"/>
@@ -52,7 +52,7 @@ period of time to allow migration from previous versions.
 
 ## Response format
 
-All responses from the API are in the JSON format.
+All responses from the API (except for remote run, shared files and shared folder that do not use it for compatibility) are in the JSON format.
 
 <pre class="language-json"><code>{
   <span class="str">"action"</span>: <span class="tag">The name of the called function</span>,
@@ -69,14 +69,15 @@ All responses from the API are in the JSON format.
 
 ## HTTP method
 
-Rudder's REST API is based on the usage of HTTP methods (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html). We use them to indicate what action will be done by the request. Currently, we use four of them:
+Rudder's API is based on the usage of HTTP methods (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html). We use them to indicate what action will be done by the request. Currently, we use four of them:
 
-* **GET**: search or retrieve information (get Rule Details, get a Group, ...)
-* **POST**: update existing objects (Update a Directive, Reload a Group, ...)
+* **HEAD**: to get information about a resource without its content
+* **GET**: to retrieve information
+* **POST**: to update information or trigger an action
+* **PUT**: to create a resource on the server
 
 <span id="api-_-Parameters"/>
 
 ## Parameters
 
 To use Rudder API, you may need to pass data attributes to the API. Most of them depends on the called function and will be described below, in the corresponding function's section.
-