Merge branch 'extend-authorization' into 'master'

v0.9 update docs

See merge request !3

README.md

@@ -17,16 +17,6 @@ The specialties of this component are
 📜 License: GNU GPL 3.0 \
 📗 Docs: <https://os-docs.iml.unibe.ch/bash-rest-api-client/>
 
+## Screenshot
 
-```text
-http.init
-http.makeRequest 'http://www.example.com/'
-```
-
-This stores the response in a variable and has no output.
-Now you can get its data, eg
-
-* http.getStatuscode     - This returns the Http status code
-* http.getResponseHeader - print Http response header
-* http.getResponseData   - get data from curl
-* http.getResponse       - get response body
+![Screenshot - example script](docs/images/screenshot_example_01.png)

docs/10_Introduction.md

@@ -19,3 +19,7 @@ The specialties of this component are
 * Bash as shell (runs on Linux - or with Cygwin or other Bash implementations on MS Windows too.)
 * Curl must be in the path
 * optional: sha1sum (for export function with autogenerated filenames only)
+
+### Screenshot
+
+![Screenshot - example script](images/screenshot_example_01.png)
\ No newline at end of file

docs/20_Installation.md

@@ -23,4 +23,6 @@ If you need it in a single script then copy it to its directory. If you need it
 
 ### 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`

docs/30_Usage.md

-# Step 1: source the script
+## First steps
+
+### Source the script
 
 You must source the rest-api-client.sh. Then its functions are usable in the current process.
 The "methods" start with "http" dot "[method]".
 
-# Step 2: Use http.* functions
+### Initialize a new request
+
+```text
+http.init
+```
+
+### Make a request
+
+```text
+http.makeRequest 'http://www.example.com/'
+```
+
+This stores the response in a variable and has no output.
+
+### Use http.* functions
+
+Now you can get its data, eg
+
+* http.getStatuscode     - This returns the Http status code
+* http.getResponseHeader - print Http response header
+* http.getResponseData   - get data from curl
+* http.getResponse       - get response body
 
 You should start with *http.help* to get an overwiew.
 
@@ -18,12 +41,12 @@ $ . ./rest-api-client.sh
 #
 $ http.help
 
-
-Bash REST API client v0.8
+Bash REST API client v0.9
 
 This is a bash solution to script REST API calls.
 
-Source:https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client
+Source: <https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client>
+Docs: <https://os-docs.iml.unibe.ch/bash-rest-api-client/>
 License: GNU GPL 3
 
 
@@ -48,11 +71,13 @@ INSTRUCTION:
 
     setAuth AUTH:PASSWORD
       Set authentication with user and password for basic auth
+      Without given parameter, authentication is removed
 
     setAuthorization TYPE TOKEN|HASH
       Set authentication with Authorization header. 
       As TYPE you can use Basic|Bearer|Negotiate|...
       2nd param is the token or hased user+password
+      Without given parameter, authorization is removed
 
     http.setBody DATA
       set a body for POST/ PUT requests.
@@ -175,3 +200,7 @@ INSTRUCTION:
         It is useful if you use the AUTOFILE mechanism.
 
 ```
+
+### Try it
+
+Execute the script `./tests/example_01_simple_get.sh` to see a basic example.

docs/40_Examples.md

@@ -114,6 +114,25 @@ fi
 echo "OK, ${myHost} was found."
 ```
 
+### POST request with Json data
+
+This snippet sends the result of a monitor check to the Json API of a Icinga sattelite. It uses `jo` to generate valid JSON.
+
+```sh
+data="$( jo  \
+    check_source=${CHECK}                          \
+    check_command="""${myFullscript} $myparams"""  \
+    exit_status=$rc                                \
+    ttl=$checkInterval                             \
+    execution_start=$iTsStart                      \
+    execution_end=$iTsEnd                          \
+    performance_data="${outPerfdata}"              \
+    plugin_output="""${output}""" 
+)"
+
+http.makeRequest POST actions/process-check-result?service=${CHECK}!${SERVICE} "$data"
+```
+
 ## Authentication with JWT token
 
 The snippet shows how to fetch a token first that will be added to be used in all following requests.
@@ -136,7 +155,10 @@ http.makeRequest GET "token"
 ACCESS_TOKEN=$(http.getResponse | jq -r .access_token)
 
 # Set token for authorization
-http.setAuthorization "Bearer ${ACCESS_TOKEN}"
+http.setAuthorization "Bearer" "${ACCESS_TOKEN}"
+
+# Unset basic auth
+http.setAuth
 
 # ---------- Requests to app or api
 http.makeRequest GET "api"

docs/99_Functions/rest-api-client.sh.md

+## rest-api-client.sh
+
+List of all functions in alphabetic order
+
+### http()
+
+[line: 94](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L94)
+
+### http.addHeader()
+
+```txt
+
+Add a line to the request header
+
+🟩 param  string  line to add, eg "Connection: keep-alive"
+
+```
+
+[line: 680](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L680)
+
+### http.dump()
+
+```txt
+
+Dump information about request and response
+
+no params
+
+```
+
+[line: 575](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L575)
+
+### http.flushCache()
+
+```txt
+
+Flush the cache
+
+no params
+
+```
+
+[line: 840](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L840)
+
+### http.getRequestAge()
+
+```txt
+
+Get age of the response in sec.
+It is especially useful after responseImport
+
+no param
+
+returns integer  age of the response in sec
+
+```
+
+[line: 422](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L422)
+
+### http.getRequestTs()
+
+```txt
+
+Get timestamp of the response as a Unix timestamp.
+
+no param
+
+returns string  the timestamp of the response
+
+```
+
+[line: 408](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L408)
+
+### http.getResponse()
+
+```txt
+
+Get response body
+
+no param
+
+returns string  the response body
+
+```
+
+[line: 441](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L441)
+
+### http.getResponseData()
+
+```txt
+
+Get curl data of this request with status, transferred bytes, speed, ...
+
+no param
+
+returns string  the response data
+
+```
+
+[line: 454](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L454)
+
+### http.getResponseHeader()
+
+```txt
+
+Get response header
+
+no param
+
+returns string  the response header
+
+```
+
+[line: 467](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L467)
+
+### http.getResponseRaw()
+
+```txt
+
+Get raw response (not available after import)
+
+no params
+
+no param
+
+```
+
+[line: 480](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L480)
+
+### http.getStatus()
+
+```txt
+
+Get Http status as string OK|Redirect|Error
+
+no params
+
+```
+
+[line: 491](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L491)
+
+### http.getStatuscode()
+
+```txt
+
+Get Http status code of the request as 3 digit number
+
+no params
+
+```
+
+[line: 504](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L504)
+
+### http.help()
+
+```txt
+
+show a help text
+
+no params
+
+```
+
+[line: 851](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L851)
+
+### http.init()
+
+```txt
+
+Initialize the client
+
+Initialize the client for a new request. Call this before any other
+function. It will reset all variables.
+
+```
+
+[line: 115](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L115)
+
+### http.isClientError()
+
+```txt
+
+Was the repsonse a client error (4xx)
+
+no params
+
+```
+
+[line: 553](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L553)
+
+### http.isError()
+
+```txt
+
+Was the repsonse a client error (4xx or 5xx)
+
+no params
+
+```
+
+[line: 542](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L542)
+
+### http.isOk()
+
+```txt
+
+Check: was response a 2xx status code?
+output is a statuscode if it matches ... or empty
+Additionally you can verify the return code
+
+$? -eq 0 means YES
+$? -ne 0 means NO
+
+no params
+
+```
+
+[line: 520](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L520)
+
+### http.isRedirect()
+
+```txt
+
+Was the repsonse a redirect?
+
+no params
+
+```
+
+[line: 531](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L531)
+
+### http.isServerError()
+
+```txt
+
+Was the repsonse a client error (5xx)
+
+no params
+
+```
+
+[line: 564](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L564)
+
+### http.loadcfg()
+
+```txt
+
+Load a config file
+
+This function is marked as deprecated.
+It will be removed in the future.
+
+🟩 param  string  config file name
+
+Sourcing that file will set the following vars
+- RestApiUser
+- RestApiPassword
+- RestApiBaseUrl
+- RestApiDocs
+
+The function will then set the "internal" vars
+- http_req__auth
+- http_req__fullurl
+- http_req__docs
+
+```
+
+[line: 283](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L283)
+
+### http.makeRequest()
+
+```txt
+
+Execute the request
+
+🔹 param  string  optional: method; GET|POST|PUT|DELETE|...
+🔹 param  string  optional: full url
+🔹 param  string  optional: request body
+
+description:
+
+This function does the following:
+
+1. Check if to use a cache
+2. If not cached, make the request
+3. If cached, use the cached result
+
+```
+
+[line: 167](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L167)
+
+### http.quit()
+
+```txt
+
+Show error message with last return code and quit with this exitcode
+
+This function is used to quit the script with a meaningful error message
+and the exit code of the last command.
+
+The message is printed to STDERR and contains the return code.
+If a documentation URL is known, it is printed as a hint.
+
+The exit code is the one of the last command.
+To prevent the script from exiting when this function is called from a
+sourced file, the exit is commented out.
+
+no params
+
+```
+
+[line: 250](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L250)
+
+### http.responseDelete()
+
+```txt
+
+Delete an exported file; this is especially useful if you use
+AUTOFILE functionality
+
+🟩 param  string  filename with stored response
+
+```
+
+[line: 651](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L651)
+
+### http.responseExport()
+
+```txt
+
+Export response to a file
+
+🔹 param  string  optional: custom filename
+
+```
+
+[line: 609](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L609)
+
+### http.responseImport()
+
+```txt
+
+Import a former response from a file
+
+🟩 param  string  filename with stored response
+
+```
+
+[line: 627](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L627)
+
+### http.setAccept()
+
+```txt
+
+set Accept request header and override default
+
+🟩 param  string  accept header value, eg text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
+
+```
+
+[line: 691](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L691)
+
+### http.setAuth()
+
+```txt
+
+Set basic authentication
+Without given parameter, authentication is removed
+
+🔹 param  string  optional: USER:PASSWORD
+
+```
+
+[line: 707](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L707)
+
+### http.setAuthorization()
+
+```txt
+
+Set authentication via Athorization header
+Without given parameter, authorization is removed
+
+🔹 param  string  optional: type, eg. Basic|Bearer|Negotiate
+🔹 param  string  optional: token or encoded user + password
+
+```
+
+[line: 724](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L724)
+
+### http.setBaseUrl()
+
+```txt
+
+Set a base url of an API
+Remark: Then use http.setUrl to complet the url to request
+
+🟩 param  string  url
+
+```
+
+[line: 751](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L751)
+
+### http.setBody()
+
+```txt
+
+Set body to send for PUTs and POSTs
+
+🟩 param  string  body
+
+```
+
+[line: 739](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L739)
+
+### http.setCacheFile()
+
+```txt
+
+Set cache file
+
+🟩 param  string  filename
+
+```
+
+[line: 829](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L829)
+
+### http.setCacheTtl()
+
+```txt
+
+Set cache ttl in seconds
+
+🟩 param  integer  ttl in seconds
+
+```
+
+[line: 818](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L818)
+
+### http.setDebug()
+
+```txt
+
+Enable or disable debug mode
+
+🟩 param  integer  0|1
+
+```
+
+[line: 763](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L763)
+
+### http.setDocs()
+
+[line: 767](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L767)
+
+### http.setFullUrl()
+
+```txt
+
+Set a full url to request
+
+🔹 param  string  optional: url
+
+```
+
+[line: 789](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L789)
+
+### http.setMethod()
+
+```txt
+
+Set the method to use; GET|POST|PUT|DELETE|...
+
+🟩 param  string  name of method
+
+```
+
+[line: 778](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L778)
+
+### http.setUrl()
+
+```txt
+
+Complete the base url
+
+🟩 param  string  url part behind base url
+
+```
+
+[line: 804](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L804)
+

rest-api-client.sh

@@ -21,9 +21,10 @@
 # 2021-01-21  v0.6  axel.hahn@iml.unibe.ch  add Content-type in request header
 # 2022-01-11  v0.7  axel.hahn@iml.unibe.ch  fixes using shellcheck
 # 2024-10-09  v0.8  axel.hahn@unibe.ch      add setAuthorization; customize accept header, add custom request headers
+# 2024-10-10  v0.9  axel.hahn@unibe.ch      update docs
 # ======================================================================
 
-  http_cfg__about="Bash REST API client v0.8"
+  http_cfg__about="Bash REST API client v0.9"
   typeset -i http_cfg__debug=0
   typeset -i http_cfg__cacheTtl=0
   http_cfg__cacheDir=/var/tmp/http-cache
@@ -69,10 +70,11 @@
 
   # ......................................................................
   #
-  # write a debug message to STDERR
+  # Write a debug message to STDERR
   # Do no not change the prefix - is is read in inc_functions
   #
   # params  strings  output message
+  #
   function http._wd(){
     if [ $http_cfg__debug -gt 0 ]; then
       echo -e "\e[33m# RESTAPI::DEBUG $*\e[0m" >&2
@@ -81,10 +83,11 @@
 
   # ......................................................................
   #
-  # write an error message to STDERR
+  # Write an error message to STDERR
   # Do no not change the prefix - is is read in inc_functions
   #
   # params  strings  output message
+  #
   function http._we(){
     echo -e "\e[31m# RESTAPI::ERROR $*\e[0m" >&2
   }
@@ -106,6 +109,10 @@ EOH
   # ......................................................................
   #
   # Initialize the client
+  #
+  # Initialize the client for a new request. Call this before any other
+  # function. It will reset all variables.
+  #
   function http.init(){
     http._wd "${FUNCNAME[0]}()"
     which curl >/dev/null || http.quit
@@ -149,6 +156,15 @@ EOH
   # param  string  optional: method; GET|POST|PUT|DELETE|...
   # param  string  optional: full url
   # param  string  optional: request body
+  #
+  # description:
+  #
+  #   This function does the following:
+  #
+  #     1. Check if to use a cache
+  #     2. If not cached, make the request
+  #     3. If cached, use the cached result
+  #
   function http.makeRequest(){
     http._wd "${FUNCNAME[0]}()"
 
@@ -220,7 +236,18 @@ EOH
   #
   # Show error message with last return code and quit with this exitcode
   #
+  # This function is used to quit the script with a meaningful error message
+  # and the exit code of the last command.
+  #
+  # The message is printed to STDERR and contains the return code.
+  # If a documentation URL is known, it is printed as a hint.
+  #
+  # The exit code is the one of the last command.
+  # To prevent the script from exiting when this function is called from a
+  # sourced file, the exit is commented out.
+  #
   # no params
+  #
   function http.quit(){
     rc=$?
     http._wd "${FUNCNAME[0]}()"
@@ -234,7 +261,26 @@ EOH
   }
 
 
-  # load a config file
+  # ......................................................................
+  #
+  # Load a config file
+  #
+  # This function is marked as deprecated.
+  # It will be removed in the future.
+  #
+  # param  string  config file name
+  #
+  # Sourcing that file will set the following vars
+  # - RestApiUser
+  # - RestApiPassword
+  # - RestApiBaseUrl
+  # - RestApiDocs
+  #
+  # The function will then set the "internal" vars
+  # - http_req__auth
+  # - http_req__fullurl
+  # - http_req__docs
+  #
   function http.loadcfg(){
     http._wd "${FUNCNAME[0]}($1) !!! DEPRECATED !!!"
     # reset expected vars from config
@@ -265,6 +311,11 @@ EOH
   # Get the response header or response body
   #
   # param  string  what to return; one of header|body
+  #
+  # Return the response header or the response body. The output is the same
+  # as that of http.getResponseHeader or http.getResponse. The difference is
+  # the implementation
+  #
   function http._fetchResponseHeaderOrBody(){
     http._wd "${FUNCNAME[0]}($1)"
     local isheader=true
@@ -289,6 +340,13 @@ EOH
   # ......................................................................
   #
   # Get the response data
+  #
+  # Return the curl meta infos like http_code, http_connect, local_ip, ...
+  # as key/ value pairs. Each line is a single key value pair.
+  #
+  # The data is extracted from the response header. The format is:
+  # ${http_req__dataprefix}|key|value|key|value|...
+  #
   function http._fetchResponseData(){
     http._wd "${FUNCNAME[0]}()"
     echo "${http_resp__all}" | sed "s#${http_req__dataprefix}#\n${http_req__dataprefix}#" | grep "${http_req__dataprefix}" | tail -1 | cut -f 2- -d "|" | sed "s#|#\n#g" | grep -v "${http_req__dataprefix}" | while read -r line; do
@@ -330,6 +388,9 @@ EOH
   # Get a section from dump data
   #
   # param  string  what to return; one of HEADER|DATA|BODY
+  #
+  # returns string  the requested part of the response
+  #
   function http._getFilteredResponse(){
     http._wd "${FUNCNAME[0]}($1)"
     echo "${http_resp__neutral}" | grep "^#_${1}_|"  | cut -f 2- -d "|"
@@ -339,7 +400,12 @@ EOH
 
   # ......................................................................
   #
-  # Get timestamp of the response
+  # Get timestamp of the response as a Unix timestamp.
+  #
+  # no param
+  #
+  # returns string  the timestamp of the response
+  #
   function http.getRequestTs(){
     http._wd "${FUNCNAME[0]}()"
     http._getFilteredResponse REQUEST | grep "^timestamp" | cut -f 2 -d ":"
@@ -350,6 +416,10 @@ EOH
   # Get age of the response in sec.
   # It is especially useful after responseImport
   #
+  # no param
+  #
+  # returns integer  age of the response in sec
+  #
   function http.getRequestAge(){
     http._wd "${FUNCNAME[0]}()"
     local iAge; typeset -i iAge
@@ -364,6 +434,11 @@ EOH
   # ......................................................................
   #
   # Get response body
+  #
+  # no param
+  #
+  # returns string  the response body
+  #
   function http.getResponse(){
     http._wd "${FUNCNAME[0]}()"
     http._getFilteredResponse BODY
@@ -372,6 +447,11 @@ EOH
   # ......................................................................
   #
   # Get curl data of this request with status, transferred bytes, speed, ...
+  #
+  # no param
+  #
+  # returns string  the response data
+  #
   function http.getResponseData(){
     http._wd "${FUNCNAME[0]}()"
     http._getFilteredResponse DATA
@@ -380,6 +460,11 @@ EOH
   # ......................................................................
   #
   # Get response header
+  #
+  # no param
+  #
+  # returns string  the response header
+  #
   function http.getResponseHeader(){
     http._wd "${FUNCNAME[0]}()"
     http._getFilteredResponse HEADER
@@ -388,6 +473,11 @@ EOH
   # ......................................................................
   #
   # Get raw response (not available after import)
+  #
+  # no params
+  #
+  # no param
+  #
   function http.getResponseRaw(){
     http._wd "${FUNCNAME[0]}()"
     echo "${http_resp__all}"
@@ -396,6 +486,9 @@ EOH
   # ......................................................................
   #
   # Get Http status as string OK|Redirect|Error
+  #
+  # no params
+  #
   function http.getStatus(){
     http._wd "${FUNCNAME[0]}($1)"
     http.isOk       >/dev/null && echo OK
@@ -406,6 +499,9 @@ EOH
   # ......................................................................
   #
   # Get Http status code of the request as 3 digit number
+  #
+  # no params
+  #
   function http.getStatuscode(){
     http._wd "${FUNCNAME[0]}()"
     http.getResponseData | grep "^http_code:" | cut -f 2 -d ":"
@@ -419,6 +515,9 @@ EOH
   #
   # $? -eq 0 means YES
   # $? -ne 0 means NO
+  #
+  # no params
+  #
   function http.isOk(){
     http._wd "${FUNCNAME[0]}()"
     http.getStatuscode | grep '2[0-9][0-9]'
@@ -427,6 +526,9 @@ EOH
   # ......................................................................
   #
   # Was the repsonse a redirect?
+  #
+  # no params
+  #
   function http.isRedirect(){
     http._wd "${FUNCNAME[0]}()"
     http.getStatuscode | grep '3[0-9][0-9]'
@@ -435,6 +537,9 @@ EOH
   # ......................................................................
   #
   # Was the repsonse a client error (4xx or 5xx)
+  #
+  # no params
+  #
   function http.isError(){
     http._wd "${FUNCNAME[0]}()"
     http.getStatuscode | grep '[45][0-9][0-9]'
@@ -443,6 +548,9 @@ EOH
   # ......................................................................
   #
   # Was the repsonse a client error (4xx)
+  #
+  # no params
+  #
   function http.isClientError(){
     http._wd "${FUNCNAME[0]}()"
     http.getStatuscode | grep '4[0-9][0-9]'
@@ -451,6 +559,9 @@ EOH
   # ......................................................................
   #
   # Was the repsonse a client error (5xx)
+  #
+  # no params
+  #
   function http.isServerError(){
     http._wd "${FUNCNAME[0]}()"
     http.getStatuscode | grep '5[0-9][0-9]'
@@ -458,7 +569,10 @@ EOH
 
   # ......................................................................
   #
-  # dump information about request and response
+  # Dump information about request and response
+  #
+  # no params
+  #
   function http.dump(){
     http._wd "${FUNCNAME[0]}()"
     http.responseExport
@@ -470,9 +584,10 @@ EOH
 
   # ......................................................................
   #
-  # helper to replace "AUTOFILE" with something uniq using full url
+  # Helper to replace "AUTOFILE" with something uniq using full url
   #
   # param  string  import or export filename
+  #
   function http._genOutfilename(){
     http._wd "${FUNCNAME[0]}($1)"
     if echo "$1" | grep -q "AUTOFILE"; then
@@ -488,8 +603,10 @@ EOH
 
   # ......................................................................
   #
-  # export response to a file
+  # Export response to a file
+  #
   # param  string  optional: custom filename
+  #
   function http.responseExport(){
     http._wd "${FUNCNAME[0]}($1)"
     if [ -z "$1" ]; then
@@ -507,6 +624,7 @@ EOH
   # Import a former response from a file
   #
   # param  string  filename with stored response
+  #
   function http.responseImport(){
     http._wd "${FUNCNAME[0]}($1)"
     local infile
@@ -530,6 +648,7 @@ EOH
   # AUTOFILE functionality
   #
   # param  string  filename with stored response
+  #
   function http.responseDelete(){
     http._wd "${FUNCNAME[0]}($1)"
     local infile
@@ -558,6 +677,7 @@ EOH
   # Add a line to the request header
   #
   # param  string  line to add, eg "Connection: keep-alive"
+  #
   function http.addHeader(){
     http._wd "${FUNCNAME[0]}($1)"
     http_req__headers+=( -H "$1")
@@ -568,6 +688,7 @@ EOH
   # set Accept request header and override default
   #
   # param  string  accept header value, eg text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
+  #
   function http.setAccept(){
     http._wd "${FUNCNAME[0]}($1)"
     if [ -z "$1" ]; then
@@ -580,8 +701,10 @@ EOH
   # ......................................................................
   #
   # Set basic authentication
+  # Without given parameter, authentication is removed
+  #
+  # param  string  optional: USER:PASSWORD
   #
-  # param  string  USER:PASSWORD
   function http.setAuth(){
     http._wd "${FUNCNAME[0]}($1)"
     if [ -z "$1" ]; then
@@ -594,9 +717,11 @@ EOH
   # ......................................................................
   #
   # Set authentication via Athorization header
+  # Without given parameter, authorization is removed
+  #
+  # param  string  optional: type, eg. Basic|Bearer|Negotiate
+  # param  string  optional: token or encoded user + password
   #
-  # param  string  type, eg. Basic|Bearer|Negotiate
-  # param  string  token or encoded user + password
   function http.setAuthorization(){
     http._wd "${FUNCNAME[0]}($1 $2)"
     if [ -z "$1" ]; then
@@ -611,6 +736,7 @@ EOH
   # Set body to send for PUTs and POSTs
   #
   # param  string  body
+  #
   function http.setBody(){
     http._wd "${FUNCNAME[0]}($1)"
     http_req__body=$1
@@ -622,6 +748,7 @@ EOH
   # Remark: Then use http.setUrl to complet the url to request
   #
   # param  string  url
+  #
   function http.setBaseUrl(){
     http._wd "${FUNCNAME[0]}($1)"
     http_req__baseurl=$1
@@ -633,6 +760,7 @@ EOH
   # Enable or disable debug mode
   #
   # param  integer  0|1
+  #
   function http.setDebug(){
     http._wd "${FUNCNAME[0]}($1)"
     http_cfg__debug=$1
@@ -647,6 +775,7 @@ EOH
   # Set the method to use; GET|POST|PUT|DELETE|...
   #
   # param  string  name of method
+  #
   function http.setMethod(){
     http._wd "${FUNCNAME[0]}($1)"
     http_req__method=$1
@@ -657,6 +786,7 @@ EOH
   # Set a full url to request
   #
   # param  string  optional: url
+  #
   function http.setFullUrl(){
     http._wd "${FUNCNAME[0]}($1)"
     if [ -z "$1" ]; then
@@ -671,6 +801,7 @@ EOH
   # Complete the base url
   #
   # param  string  url part behind base url
+  #
   function http.setUrl(){
     http._wd "${FUNCNAME[0]}($1)"
     http_req__url=$1
@@ -684,6 +815,7 @@ EOH
   # Set cache ttl in seconds
   #
   # param  integer  ttl in seconds
+  #
   function http.setCacheTtl(){
     http._wd "${FUNCNAME[0]}($1)"
     http_cfg__cacheTtl=$1
@@ -694,6 +826,7 @@ EOH
   # Set cache file
   #
   # param  string  filename
+  #
   function http.setCacheFile(){
     http._wd "${FUNCNAME[0]}($1)"
     http_cfg__cacheFile="$1"
@@ -702,6 +835,9 @@ EOH
   # ......................................................................
   #
   # Flush the cache  
+  #
+  # no params
+  #
   function http.flushCache(){
     http._wd "${FUNCNAME[0]}($1)"
     rm -f ${http_cfg__cacheDir}/*
@@ -710,7 +846,9 @@ EOH
   # ......................................................................
   #
   # show a help text
+  #
   # no params
+  #
   function http.help(){
     cat <<EOH
 
@@ -744,11 +882,13 @@ INSTRUCTION:
 
     setAuth AUTH:PASSWORD
       Set authentication with user and password for basic auth
+      Without given parameter, authentication is removed
 
     setAuthorization TYPE TOKEN|HASH
       Set authentication with Authorization header. 
       As TYPE you can use Basic|Bearer|Negotiate|...
       2nd param is the token or hased user+password
+      Without given parameter, authorization is removed
 
     http.setBody DATA
       set a body for POST/ PUT requests.

scripts/generate_bash_docs.sh

+#!/bin/bash
+
+cd "$( dirname "$0" )" || exit
+
+BASHDOC=/home/axel/data/opensource/bash/bashdoc/bashdoc2md.sh
+
+SOURCES=../rest-api-client.sh
+TARGETBASE=../docs/99_Functions
+REPO=https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/
+
+
+echo
+echo "GENERATE MARKDOWN DOCS"
+echo
+
+for SOURCE in $SOURCES
+do
+    TARGET="$TARGETBASE/$(basename "$SOURCE").md"
+
+    if [ "$TARGET" -nt "$SOURCE" ] && [ "$TARGET" -nt "$BASHDOC" ]; then
+        echo "SKIP: $TARGET is up to date."
+    else
+        rm -f "$TARGET"
+        echo "Generating $TARGET ... "
+        $BASHDOC -l 2 -r "$REPO" "$SOURCE" > "$TARGET"
+    fi
+    ls -l "$SOURCE" "$TARGET"
+    echo
+done
+echo "Done."