[3.5] hotbackup path normalisation and list documentation updates (#10143)

* path normalisation upload

* path normalisation download

* added documentation to hot backup APIs

* added new parameters

* added new parameters

* Polish docublocks.

Documentation/DocuBlocks/Rest/BackupRestore/post_admin_backup_create.md

@@ -12,8 +12,6 @@ guarantee consistency. Note that the backup at first resides on the
 same machine and hard drive as the original data. Make sure to upload
 it to a remote site for an actual backup.
 
-The body of the request may contain an object with the following attributes:
-
 @RESTBODYPARAM{label,string,optional,string}
 The label for this backup. The label is used together with a
 timestamp string create a unique backup identifier, `<timestamp>_<label>`.
@@ -65,4 +63,6 @@ within the timeout, then an *HTTP 408* is returned.
     };
 @END_EXAMPLE_ARANGOSH_RUN
 
+The result `body` contains besides the above discussed error codes the `result` object, if `code` is equal to `201`, which holds the unique identifier of this hot backup as the string attibute `id`, the full size in bytes as `sizeInBytes`, the number of idividual files as `nrFiles` and the number of database servers as `nrDBServers`. Single server deployments list potentially misleadingly `nrDBServers: 1`. Furthermore, the body contains a `datetime` time stamp and the flag `potentiallyInconsistent`, which indicates that the backup could inconsistent. This only happens if `allowInconsistent` has happened.
+
 @endDocuBlock

Documentation/DocuBlocks/Rest/BackupRestore/post_admin_backup_download.md

@@ -16,7 +16,7 @@ attribute.
 @RESTBODYPARAM{remoteRepository,string,required,string}
 URL of remote reporsitory. This is required when a download
 operation is scheduled. In this case leave out the `downloadId`
-attribute.
+attribute. Provided repository URLs are normalized and validated as follows: One single colon must appear separating the configurtion section name and the path. The URL prefix up to the colon must exist as a key in the config object below. No slashes must appear before the colon. Multiple back to back slashes are collapsed to one, as `..` and `.` are applied accordingly. Local repositories must be absolute paths and must begin with a `/`. Trailing `/` are removed.  
 
 @RESTBODYPARAM{config,object,required,object}
 Configuration of remote repository. This is required when a download
@@ -98,6 +98,8 @@ there is no known download operation with the given `downloadId`.
     };
 @END_EXAMPLE_ARANGOSH_RUN
 
+The `result` object of the body holds the `downloadId` string attribute which can be used to follow the download process.
+
 @EXAMPLE_ARANGOSH_RUN{RestBackupDownloadBackupStarted_rocksdb}
     var hotbackup = require("@arangodb/hotbackup");
     try {
@@ -150,4 +152,5 @@ there is no known download operation with the given `downloadId`.
     };
 @END_EXAMPLE_ARANGOSH_RUN
 
+
 @endDocuBlock

Documentation/DocuBlocks/Rest/BackupRestore/post_admin_backup_list.md

@@ -60,4 +60,6 @@ method other than `POST`, then an *HTTP 405 METHOD NOT ALLOWED* is returned.
     };
 @END_EXAMPLE_ARANGOSH_RUN
 
+The result consists of a `list` object of hot backups by their `id`, where `id` uniquely identifies a specific hot backup, `version` depicts the version of ArangoDB, which was used to create any individual hot backup and `datetime` displays the time of creation of the hot backup. Further parameters are the size of the backup in bytes as `sizeInBytes`, the number of individual data files as `nrFiles`, the number of db servers at time of creation as `nrDBServers`, the number of backup parts, which are found on the currently reachable db servers as `nrPiecesPresent`. If the backup was created allowing inconsistences, it is so denoted as `potentiallyInconsistent`. The `available` boolean parameter is tightly connected to the backup to be present and ready to be restored on all db servers. It is `true` except, when the number of db servers currently reachable does not match to the number of db servers listed in the backup.   
+
 @endDocuBlock

Documentation/DocuBlocks/Rest/BackupRestore/post_admin_backup_restore.md

@@ -8,8 +8,6 @@ Restores a consistent backup from a
 snapshot in time, with a given id. The backup snapshot must reside on
 the ArangoDB service locally.
 
-The request may contain an object with the following attributes:
-
 @RESTBODYPARAM{id,string,required,string}
 The id of the backup to restore from.
 
@@ -67,4 +65,6 @@ are detailed in the returned error document.
     }
 @END_EXAMPLE_ARANGOSH_RUN
 
+The `result` object returns the `id` of the fail safe hot backup to return to, if necessary. And the all telling `isCluster` boolean attribute.
+
 @endDocuBlock

Documentation/DocuBlocks/Rest/BackupRestore/post_admin_backup_upload.md

@@ -16,7 +16,7 @@ attribute.
 @RESTBODYPARAM{remoteRepository,string,optional,string}
 URL of remote reporsitory. This is required when an upload
 operation is scheduled. In this case leave out the `uploadId`
-attribute.
+attribute. Provided repository URLs are normalized and validated as follows: One single colon must appear separating the configurtion section name and the path. The URL prefix up to the colon must exist as a key in the config object below. No slashes must appear before the colon. Multiple back to back slashes are collapsed to one, as `..` and `.` are applied accordingly. Local repositories must be absolute paths and must begin with a `/`. Trailing `/` are removed.    
 
 @RESTBODYPARAM{config,object,optional,object}
 Configuration of remote repository. This is required when an upload
@@ -83,6 +83,8 @@ there is no known upload operation with the given `uploadId`.
     };
 @END_EXAMPLE_ARANGOSH_RUN
 
+The `result` object of the body holds the `uploadId` string attribute which can be used to follow the upload process.
+
 @EXAMPLE_ARANGOSH_RUN{RestBackupUploadBackupStarted_rocksdb}
     try {
       require("fs").makeDirectory("/tmp/backups");