From f56b8a8fe0fc47b82b1ca6390acf3c3f44d71ca3 Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@unibe.ch>
Date: Tue, 19 Nov 2024 17:04:45 +0100
Subject: [PATCH] update docs

---
 docs/20_Changelog.md                          |  11 ++
 docs/20_Installation.md                       |   4 +-
 docs/30_Quickstart.md                         |   4 +-
 docs/40_Usage.md                              |  35 ++++--
 docs/50_Examples.md                           |   2 +-
 ...rest-api-client.sh.md => http.class.sh.md} | 112 ++++++++++++------
 scripts/generate_bash_docs.sh                 |   2 +-
 7 files changed, 117 insertions(+), 53 deletions(-)
 create mode 100644 docs/20_Changelog.md
 rename docs/99_Functions/{rest-api-client.sh.md => http.class.sh.md} (51%)

diff --git a/docs/20_Changelog.md b/docs/20_Changelog.md
new file mode 100644
index 0000000..52512ae
--- /dev/null
+++ b/docs/20_Changelog.md
@@ -0,0 +1,11 @@
+## Changelog
+
+### v0.11 (2024-11-20)
+
+This release was published to disable insecure requests.
+
+❌ Removed: curl default parameter `-k` (it disables ssl verification)
+⚠️ Deprecated: The new filename is `http.class.sh`. When using `rest-api-client.sh` you get a deprecated warning on STDERR
+🔷 Added: function `http.setInsecure` - set "1" to enable `-k` again; use no parameter to disable
+🔷 Added: function `http.setCA "<file>"` to define a custom ca file (results in `--cacert <file>`)
+🔷 Added: function `http.addCurlparam "<parameter>"` to add any missing curl parameter
diff --git a/docs/20_Installation.md b/docs/20_Installation.md
index 8028dab..e774315 100644
--- a/docs/20_Installation.md
+++ b/docs/20_Installation.md
@@ -18,11 +18,11 @@ Download the archive i.e. as zip:
 
 #### Copy shell script somewhere
 
-Copy the file `rest-api-client.sh` anywhere you need it.
+Copy the file `http.class.sh` anywhere you need it.
 If you need it in a single script then copy it to its directory. If you need it more often then copy it to a folter of your PATH environment.
 
 ### Get the script only
 
 For pure functionality without docs and more you can download the script itself
 
-`wget https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/raw/master/rest-api-client.sh`
+`wget https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/raw/master/http.class.sh`
diff --git a/docs/30_Quickstart.md b/docs/30_Quickstart.md
index 132394a..25259b0 100644
--- a/docs/30_Quickstart.md
+++ b/docs/30_Quickstart.md
@@ -1,6 +1,6 @@
 ## Source the script
 
-You must source the rest-api-client.sh. Then its functions are usable in the current process.
+You must source the `http.class.sh`. Then its functions are usable in the current process.
 The "methods" start with "http" dot "[method]".
 
 ## Initialize a new request
@@ -32,7 +32,7 @@ Now you can get its data, eg
 #!/bin/bash
 
 cd "$( dirname "$0" )" || exit
-. ../rest-api-client.sh || exit 1
+. ../http.class.sh || exit 1
 
 http.init
 http.makeRequest GET "http://www.example.com/"
diff --git a/docs/40_Usage.md b/docs/40_Usage.md
index 6cb16b6..c43d79a 100644
--- a/docs/40_Usage.md
+++ b/docs/40_Usage.md
@@ -2,13 +2,13 @@
 
 ### Source the script
 
-You must source the rest-api-client.sh. Then its functions are usable in the current process.
+You must source the `http.class.sh`. Then its functions are usable in the current process.
 The "methods" start with "http" dot "[method]".
 
 ```sh
 #!/bin/bash
 cd "$( dirname "$0" )" || exit
-. ./rest-api-client.sh || exit 1
+. ./http.class.sh || exit 1
 
 ```
 
@@ -88,9 +88,12 @@ Define a base url that will be used as prefix when making a request to a relativ
 #### Other funtions
 
 * `http.setAccept <ACCEPT>`
-* `http.setDocs URL` http.setMethod METHOD Set a http method. Use an uppercase string for GET|POST|PUT|DELETE|...
-* `http.addHeader HEADER_LINE` Add a header line to the request. This command can be repeated multiple times.
-* `http.setDocs` Set a docs url. If set it will be shown as additional hint when a request fails.
+* `http.setMethod <METHOD>` Set a http method. Use an uppercase string for GET|POST|PUT|DELETE|... (any method)
+* `http.setCA <FILE>` Set a ca cert file (it results in --cacert \<file\>). Without parameter this flag will be removed.
+* `http.setDocs <URL>` Set a docs url. If set it will be shown as additional hint when a request fails.
+* `http.setInsecure 1` Do not verify SSL certificate (it results in `-k` parameter not recommended). Without parameter this flag will be removed.
+* `http.addHeader <HEADER_LINE>` Add a header line to the request. This command can be repeated multInsecure 1
+* `http.addCurlparam <parameter>` Add any mising curl parameter when making the requests. This command can be repeated multiple times.
 
 ## Make a request
 
@@ -263,14 +266,14 @@ You can run `http.help` to get an overwiew over all functions.
 #
 # step one: source the shell script
 #
-$ . ./rest-api-client.sh
+$ . ./http.class.sh
 
 #
 # then use its functions.
 #
 $ http.help
 
-Bash REST API client v0.10
+Bash REST API client v0.11
 
 This is a bash solution to script REST API calls.
 
@@ -316,10 +319,20 @@ INSTRUCTION:
       renmark:
       Use http.setUrl to built a complete url.
 
+    http.setCA "<FILE>"
+      Set CA file to verify the server certificate. 
+      Default: [empty] = use system defaults
+      Without parameter the cafile is removed
+
     http.setDocs "<URL>"
       Set a docs url. If set it will be shown as additional hint when a 
       request fails.
 
+    http.setInsecure 1
+      Set insecure flag by giving any non empty value. 
+      Default: [empty] = secure requests
+      Without parameter the insecure flag is removed
+
     http.setMethod "<METHOD>"
       Set a http method. Use an uppercase string for GET|POST|PUT|DELETE|...
 
@@ -332,7 +345,12 @@ INSTRUCTION:
 
     http.addHeader "<HEADER_LINE>"
       Add a header line to the request.
-      This command can be repeated multiple times.
+      This command can be repeated multiple times to add multiple headers.
+
+    http.addCurlparam "<CURL_PARAMETER>"
+      Add any missing parameter for curl requestst.
+      This command can be repeated multiple times to add multiple prameters.
+      You also can add multiple parameters with one command.
 
 - caching functions
 
@@ -417,7 +435,6 @@ INSTRUCTION:
         Example:
         http.makeRequest "https://example.com/api/"
         http.responseExport /tmp/something_AUTOFILE_.txt
-
       http.responseImport "<FILE>"
         Import an export file.
         To use the AUTOFILE mechanism from export set
diff --git a/docs/50_Examples.md b/docs/50_Examples.md
index 1a8c857..51e3b9a 100644
--- a/docs/50_Examples.md
+++ b/docs/50_Examples.md
@@ -4,7 +4,7 @@ A required step is sourcing the script to make the http.* function available in
 
 ```sh
 # --- source script
-> . ./rest-api-client.sh 
+> . ./http.class.sh 
 ```
 
 Then you can follow the examples.
diff --git a/docs/99_Functions/rest-api-client.sh.md b/docs/99_Functions/http.class.sh.md
similarity index 51%
rename from docs/99_Functions/rest-api-client.sh.md
rename to docs/99_Functions/http.class.sh.md
index 7ee93f1..b0ad8ea 100644
--- a/docs/99_Functions/rest-api-client.sh.md
+++ b/docs/99_Functions/http.class.sh.md
@@ -1,10 +1,22 @@
-## rest-api-client.sh
+## http.class.sh
 
 List of all functions in alphabetic order
 
 ### http()
 
-[line: 96](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L96)
+[line: 97](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L97)
+
+### http.addCurlparam()
+
+```txt
+
+Add an additional curl parameter
+
+🟩 param  string  line to add, eg "Connection: keep-alive"
+
+```
+
+[line: 701](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L701)
 
 ### http.addHeader()
 
@@ -16,7 +28,7 @@ Add a line to the request header
 
 ```
 
-[line: 682](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L682)
+[line: 690](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L690)
 
 ### http.dump()
 
@@ -28,7 +40,7 @@ no params
 
 ```
 
-[line: 577](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L577)
+[line: 585](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L585)
 
 ### http.flushCache()
 
@@ -40,7 +52,7 @@ no params
 
 ```
 
-[line: 842](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L842)
+[line: 884](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L884)
 
 ### http.getRequestAge()
 
@@ -55,7 +67,7 @@ returns integer  age of the response in sec
 
 ```
 
-[line: 424](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L424)
+[line: 432](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L432)
 
 ### http.getRequestTs()
 
@@ -69,7 +81,7 @@ returns string  the timestamp of the response
 
 ```
 
-[line: 410](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L410)
+[line: 418](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L418)
 
 ### http.getResponse()
 
@@ -83,7 +95,7 @@ returns string  the response body
 
 ```
 
-[line: 443](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L443)
+[line: 451](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L451)
 
 ### http.getResponseData()
 
@@ -97,7 +109,7 @@ returns string  the response data
 
 ```
 
-[line: 456](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L456)
+[line: 464](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L464)
 
 ### http.getResponseHeader()
 
@@ -111,7 +123,7 @@ returns string  the response header
 
 ```
 
-[line: 469](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L469)
+[line: 477](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L477)
 
 ### http.getResponseRaw()
 
@@ -125,7 +137,7 @@ no param
 
 ```
 
-[line: 482](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L482)
+[line: 490](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L490)
 
 ### http.getStatus()
 
@@ -137,7 +149,7 @@ no params
 
 ```
 
-[line: 493](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L493)
+[line: 501](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L501)
 
 ### http.getStatuscode()
 
@@ -149,7 +161,7 @@ no params
 
 ```
 
-[line: 506](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L506)
+[line: 514](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L514)
 
 ### http.help()
 
@@ -161,7 +173,7 @@ no params
 
 ```
 
-[line: 853](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L853)
+[line: 895](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L895)
 
 ### http.init()
 
@@ -174,7 +186,7 @@ function. It will reset all variables.
 
 ```
 
-[line: 117](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L117)
+[line: 118](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L118)
 
 ### http.isClientError()
 
@@ -186,7 +198,7 @@ no params
 
 ```
 
-[line: 555](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L555)
+[line: 563](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L563)
 
 ### http.isError()
 
@@ -198,7 +210,7 @@ no params
 
 ```
 
-[line: 544](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L544)
+[line: 552](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L552)
 
 ### http.isOk()
 
@@ -215,7 +227,7 @@ no params
 
 ```
 
-[line: 522](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L522)
+[line: 530](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L530)
 
 ### http.isRedirect()
 
@@ -227,7 +239,7 @@ no params
 
 ```
 
-[line: 533](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L533)
+[line: 541](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L541)
 
 ### http.isServerError()
 
@@ -239,7 +251,7 @@ no params
 
 ```
 
-[line: 566](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L566)
+[line: 574](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L574)
 
 ### http.loadcfg()
 
@@ -265,7 +277,7 @@ The function will then set the "internal" vars
 
 ```
 
-[line: 285](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L285)
+[line: 293](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L293)
 
 ### http.makeRequest()
 
@@ -287,7 +299,7 @@ This function does the following:
 
 ```
 
-[line: 169](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L169)
+[line: 173](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L173)
 
 ### http.quit()
 
@@ -309,7 +321,7 @@ no params
 
 ```
 
-[line: 252](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L252)
+[line: 260](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L260)
 
 ### http.responseDelete()
 
@@ -322,7 +334,7 @@ AUTOFILE functionality
 
 ```
 
-[line: 653](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L653)
+[line: 661](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L661)
 
 ### http.responseExport()
 
@@ -334,7 +346,7 @@ Export response to a file
 
 ```
 
-[line: 611](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L611)
+[line: 619](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L619)
 
 ### http.responseImport()
 
@@ -346,7 +358,7 @@ Import a former response from a file
 
 ```
 
-[line: 629](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L629)
+[line: 637](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L637)
 
 ### http.setAccept()
 
@@ -358,7 +370,7 @@ set Accept request header and override default
 
 ```
 
-[line: 693](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L693)
+[line: 712](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L712)
 
 ### http.setAuth()
 
@@ -371,7 +383,7 @@ Without given parameter, authentication is removed
 
 ```
 
-[line: 709](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L709)
+[line: 728](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L728)
 
 ### http.setAuthorization()
 
@@ -385,7 +397,7 @@ Without given parameter, authorization is removed
 
 ```
 
-[line: 726](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L726)
+[line: 745](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L745)
 
 ### http.setBaseUrl()
 
@@ -398,7 +410,7 @@ Remark: Then use http.setUrl to complet the url to request
 
 ```
 
-[line: 753](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L753)
+[line: 772](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L772)
 
 ### http.setBody()
 
@@ -410,7 +422,19 @@ Set body to send for PUTs and POSTs
 
 ```
 
-[line: 741](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L741)
+[line: 760](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L760)
+
+### http.setCA()
+
+```txt
+
+set and unset CA cert file to use
+
+🔹 param  string  optional: filename to use; no value to disable cafile
+
+```
+
+[line: 784](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L784)
 
 ### http.setCacheFile()
 
@@ -422,7 +446,7 @@ Set cache file
 
 ```
 
-[line: 831](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L831)
+[line: 873](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L873)
 
 ### http.setCacheTtl()
 
@@ -434,7 +458,7 @@ Set cache ttl in seconds
 
 ```
 
-[line: 820](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L820)
+[line: 862](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L862)
 
 ### http.setDebug()
 
@@ -446,11 +470,11 @@ Enable or disable debug mode
 
 ```
 
-[line: 765](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L765)
+[line: 795](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L795)
 
 ### http.setDocs()
 
-[line: 769](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L769)
+[line: 801](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L801)
 
 ### http.setFullUrl()
 
@@ -462,7 +486,19 @@ Set a full url to request
 
 ```
 
-[line: 791](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L791)
+[line: 833](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L833)
+
+### http.setInsecure()
+
+```txt
+
+Allow and disallow insecure connections
+
+🔹 param  string  optional: 1 to enable insecure flag; no value to disable insecure flag
+
+```
+
+[line: 811](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L811)
 
 ### http.setMethod()
 
@@ -474,7 +510,7 @@ Set the method to use; GET|POST|PUT|DELETE|...
 
 ```
 
-[line: 780](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L780)
+[line: 822](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L822)
 
 ### http.setUrl()
 
@@ -486,7 +522,7 @@ Complete the base url
 
 ```
 
-[line: 806](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L806)
+[line: 848](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/http.class.sh#L848)
 
 - - -
 Generated with [Bashdoc](https://github.com/axelhahn/bashdoc) v0.6
diff --git a/scripts/generate_bash_docs.sh b/scripts/generate_bash_docs.sh
index e353eee..f66dc42 100755
--- a/scripts/generate_bash_docs.sh
+++ b/scripts/generate_bash_docs.sh
@@ -4,7 +4,7 @@ cd "$( dirname "$0" )" || exit
 
 BASHDOC=/home/axel/data/opensource/bash/bashdoc/bashdoc2md.sh
 
-SOURCES=../rest-api-client.sh
+SOURCES=../http.class.sh
 TARGETBASE=../docs/99_Functions
 REPO=https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/
 
-- 
GitLab