Merge branch 'extend-authorization' into 'master'

Extend authorization: update docs and help

See merge request !5

README.md

 # Bash REST API client
 
+A set of class like functions with a <code>http.</code> prefix.
 This is a bash solution to script REST API calls.
 
 The specialties of this component are
@@ -7,8 +8,8 @@ The specialties of this component are
 * It was build to simplify http calls and handle http response for scripts
 * After making a request the response stays is in memory. There is no output to any file to grep something or to cleanup after usage.
 * Its functions feel a bit like class methods, i.e. http.getResponse to get the response body or http.getResponseHeader for the Http response header
-* This component wraps curl - ist supports any http method
-* works with anonymous requests and Basic Authentication
+* This component wraps curl - it supports any http method
+* works with anonymous requests and authentication / authorization: (Basic authentication, Authorization header (tokens, NTLM) or any other request header variable
 * The response can be stored ... and reimported later. After import you can use the http.get* functions to fetch results from the former request.
 * Caching support for GET requests with a given TTL: if you repeat a request to the same url and ttl was not reached yet then you continue with the cached result
 

docs/10_Introduction.md

@@ -9,8 +9,8 @@ The specialties of this component are
 * It was build to simplify http calls and handle http response for scripts
 * After making a request the response stays is in memory. There is no output to any file to grep something or to cleanup after usage.
 * Its functions feel a bit like class methods, i.e. http.getResponse to get the response body or http.getResponseHeader for the Http response header
-* This component wraps curl - ist supports any http method
-* works with anonymous requests and Basic Authentication
+* This component wraps curl - it supports any http method
+* works with anonymous requests and authentication / authorization: (Basic authentication, Authorization header (tokens, NTLM) or any other request header variable
 * The response can be stored ... and reimported later. After import you can use the http.get* functions to fetch results from the former request.
 * Caching support for GET requests with a given TTL: if you repeat a request to the same url and ttl was not reached yet then you continue with the cached result
 

docs/30_Quickstart.md

+## 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]".
+
+## 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.getStatus         - This returns a string - one of Ok|Redirect|Error
+* http.getResponseHeader - print Http response header
+* http.getResponse       - get response body
+
+## Example script
+
+```sh
+#!/bin/bash
+
+cd "$( dirname "$0" )" || exit
+. ../rest-api-client.sh || exit 1
+
+http.init
+http.makeRequest GET "http://www.example.com/"
+
+http.getStatuscode
+http.getResponseHeader
+```
+
+A single request shows no advantages yet.
+You need authentication? You make multiple requests to the same API? Then you should continue.
+
+## Try it
+
+Execute the script `./tests/example_01_simple_get.sh` to see a basic example.
+
+![Screenshot - example script](images/screenshot_example_01.png)

docs/30_Usage.md → docs/40_Usage.md

-## First steps
+## Initialize
 
 ### 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]".
 
+```sh
+#!/bin/bash
+cd "$( dirname "$0" )" || exit
+. ./rest-api-client.sh || exit 1
+
+```
+
 ### Initialize a new request
 
-```text
+Start a new request. It resets internal vars of the last request.
+
+```sh
 http.init
 ```
 
-### Make a request
+### Define a request
 
-```text
-http.makeRequest 'http://www.example.com/'
-```
+If you make multiple requests to the same backend you can pre define settings for all your requests.
+
+* Use authentication
+* Instead of requesting a full url you can set a base url to handle relative urls only when making a request
+* set Accept header or any other line in the request header
+
+#### Authentication
+
+If you access protected applications or APIs that require an authentication or authorization you can send credentials or tokens to login / authorize.
+
+See also the examples in the next page that show different authorization types.
+
+##### Basic authentication
+
+You should use the function `http.setAuth "<USER>:<PASSWORD>"`.
+
+Internal info: This will add `-u "<USER>:<PASSWORD>"` in your curl requests.
+
+Parameters:
+
+* `"<USER>:<PASSWORD>"`: give a single string with Username + `:` + password in clear text.
+
+Remove basic auth:
+
+Use `http.setAuth` (without parameters) to remove the -u parameter for the next request(s).
+
+##### Authorization header
+
+A few authorization mechanisms use the variable `Authorization` in the request header.
+For those use `http.setAuthorization <TYPE> <TOKEN|HASH>`. It will insert the curl parameter -H `Authorization: <TYPE> <TOKEN|HASH>`.
+
+Parameters:
+
+* As TYPE you can use Basic|Bearer|Negotiate|...
+* The 2nd param is the token or hashed "<USER>:<PASSWORD>". A token is added as is. If a password must be encoded/ crypted you need put the encoded string here.
+
+Remove authorization header:
+
+Use `http.setAuthorization` (without parameters) to remove the authorization header for the next request(s).
+
+##### Other Authorizations
+
+If a backend needs another Variable in the request header for authorization then there is the function `http.addHeader <HEADER_LINE>`. With it you can put multiple request header variables for all your next resquests - not only for authorizations.
+
+Parameters:
+
+* `"<HEADER_LINE>"` a single string with the complete line to add.
+
+Example:
+
+`http.addHeader "PRIVATE-TOKEN: glpat-12345678"`
+
+Remove custom header:
+
+There is no way to remove a single header line that was added once.
+But you can use `http.init` to start over.
+
+#### Set url
+
+Define a base url that will be used as prefix when making a request to a relative url.
+
+* `http.setBaseUrl "<base-url>"`
+
+#### 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.
+
+## Make a request
+
+To start the request use `http.makeRequest [[METHOD] [URL] [BODY]]`.
+
+The parameters are optional. Without parameter the request will be started with given data in http.set* functions described above.
+If minimum one param is given then they are handled:
+  
+* METHOD  optional: set a method (must be uppercase) - see http.setMethod
+* URL     set a relative url - see http.setUrl
+* BODY    optional: set a body - see http.setBody
 
 This stores the response in a variable and has no output.
 
-### Use http.* functions
+The request will be skipped and uses a cached content if ...
+
+* METHOD is GET
+* http.setCacheTtl set a value > 0
+* the cache file exists and is younger than the given TTL
 
-Now you can get its data, eg
+### Request multiple urls
 
-* 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
+When performing multiple requests to the same backend use `http.setBaseUrl <URL>` to set a base url first.
 
-You should start with *http.help* to get an overwiew.
+```sh
+http.setBaseUrl "https://api.example.com/v1"
+
+http.makeRequest '/products'
+  # this is now the same like 
+  # http.makeRequest GET 'https://api.example.com/v1/products'
+
+# other requests to the same backend
+http.makeRequest '/products/72'
+http.makeRequest '/orders'
+```
+
+or
+
+```sh
+http.setBaseUrl "https://api.example.com/v1"
+
+http.setUrl "/products"
+http.makeRequest
+  # this is now the same like 
+  # http.makeRequest GET 'https://api.example.com/v1/products'
+```
+
+To breakout from the backend with the set base url, start a request with same Authentication + header settings and turning back you can do this:
+
+* request a full url directly
+
+  ```sh
+  http.makeRequest "https://www.example.com/userinfos"
+  ```
+
+* use http.setFullUrl
+
+  ```sh
+  http.setFullUrl "<another-url>"
+  http.makeRequest
+  ```
+
+Using a full url does not overwrite the base url. The next request with relative url uses the former base url again.
+
+### Other functions
+
+Next to the url you there are functions to set the other parameter values of http.makreRequest in a single function:
+
+* `http.setBody DATA` - set a body for PUT / POST requests
+* `http.setMethod METHOD` - set another method with uppercase name (default: GET)
+
+## Get response
+
+There are 3 function to get the output of response data as multiline text
+
+* `http.getResponseHeader` print http response header
+* `http.getResponse`       get response body
+* `http.getResponseData`   get data from curl
+
+## Get status
+
+There is a set of function to get infirmation about the sttaus of the request.
+
+* `http.getStatuscode` returns the Http status code with 3 digit number
+* `http.getStatus`     returns a string - one of Ok|Redirect|Error
+
+Additionally there are these status functions. 
+
+* `http.isOk` Check if the http response code is a 2xx
+* `http.isRedirect` Check if the http response code is a 3xx
+* `http.isError` Check if the http response code is a 4xx or 5xx
+* `http.isClientError` Check if the http response code is a 4xx
+* `http.isServerError` Check if the http response code is a 5xx
+
+They call http.getStatus and grep for a http status code. They show the status code and have returncode 0 if true. If you don't nedd the status code then redirect it to /dev/null.
+
+Snippet:
+
+```sh
+http.makeRequest "/products"
+
+if http.isOk > /dev/null; then
+    echo "Yep, it was OK"
+fi
+```
+
+## Caching
+
+You can store the response locally. It can be useful for requests with longer response time. Or maybe you jump between diffferent urls and want to cache them during the current script run.
+
+Default: Caching is off
+
+This feature requires an installed `sha1sum` binary.
+
+* `http.setCacheTtl <SECONDS>` Enable caching for N seconds. Remark: only GET requests will be cached. Default: 0 (no caching)
+* `http.setCacheFile "<FILENAME>"` Set a file where to read/ store a request; Default: empty; autogenerated file below /var/tmp/http-cache
+* `http.flushCache` Delete all files in `/var/tmp/http-cache`
+
+Snippet:
+
+```sh
+# set a caching time of 3 sec
+http.setCacheTtl 3
+
+# 1st request: uncached
+time http.makeRequest "/users?per_page=100"
+    # real    0m0.533s
+    # user    0m0.093s
+    # sys     0m0.107s
+
+sleep 2
+
+# 2nd request: uses caching
+time http.makeRequest "/users?per_page=100"
+    # real    0m0.020s   <<--- caching is active
+    # user    0m0.022s
+    # sys     0m0.009s
+
+sleep 2
+
+# 3rd request: TTL 3 sec is over after 2 x sleeping 2 sec
+time http.makeRequest "/users?per_page=100"
+    # Real    0m0.578s   <<--- cache is expired - a new request was made
+    # user    0m0.097s
+    # sys     0m0.099s
+
+# remove cached datA
+http.flushCache
+```
+
+## Import/ Export
+
+If you want to keep all response data of a request then you can store it to a file and import it later.
+
+* `http.responseExport ["<FILE>"]`
+* `http.responseImport "<FILE>"`
+* `http.responseDelete "<FILE>"`
+
+After importing an older Response you can apply all function to get response data or http status.
+Additionally these functions are useful:
+
+* `http.getRequestAge` Get age of the response in sec. It is especially useful after responseImport
+* `http.getRequestTs` Get timestamp of the response as a Unix timestamp.
+
+## Help: list all functions
+
+You can run `http.help` to get an overwiew over all functions.
 
 ```text
 #
@@ -41,7 +270,7 @@ $ . ./rest-api-client.sh
 #
 $ http.help
 
-Bash REST API client v0.9
+Bash REST API client v0.10
 
 This is a bash solution to script REST API calls.
 
@@ -56,7 +285,7 @@ INSTRUCTION:
 - Then you can run functions starting with "http."
 
     http.init
-      Start a new request. It resets internal vars of the last response
+      Start a new request. It resets internal vars of the last request
       (if there was one).
 
     http.setDebug 0|1
@@ -65,52 +294,54 @@ INSTRUCTION:
 
 - initialize a request
 
-    setAccept ACCEPT
+    setAccept "<ACCEPTHEADER>"
       Set authentication with user and password for basic auth
       Default: application/json
 
-    setAuth AUTH:PASSWORD
+    setAuth "<USER>:<PASSWORD>"
       Set authentication with user and password for basic auth
       Without given parameter, authentication is removed
 
-    setAuthorization TYPE TOKEN|HASH
+    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
+      2nd param is the token or hashed user+password
       Without given parameter, authorization is removed
 
-    http.setBody DATA
+    http.setBody "<DATA>"
       set a body for POST/ PUT requests.
 
-    http.setBaseUrl URL
+    http.setBaseUrl "<URL>"
       Set a base url to an api.
       renmark:
       Use http.setUrl to built a complete url.
 
-    http.setDocs URL
+    http.setDocs "<URL>"
+      Set a docs url. If set it will be shown as additional hint when a 
+      request fails.
 
-    http.setMethod METHOD
+    http.setMethod "<METHOD>"
       Set a http method. Use an uppercase string for GET|POST|PUT|DELETE|...
 
-    http.setFullUrl URL
+    http.setFullUrl "<URL>"
       Set a complete url for a request.
 
-    http.setUrl REQUEST?QUERY
+    http.setUrl "<REQUEST?QUERY>"
       Set a relative url for a request.
       This requires to use http.setBaseUrl before.
 
-    http.addHeader HEADER_LINE
+    http.addHeader "<HEADER_LINE>"
       Add a header line to the request.
       This command can be repeated multiple times.
 
 - caching functions
 
-    http.setCacheTtl SECONDS
+    http.setCacheTtl <SECONDS>
       Enable caching with values > 0
       Remark: only GET requests will be cached.
       Default: 0 (no caching)
 
-    http.setCacheFile FILENAME
+    http.setCacheFile "<FILENAME>"
       Set a file where to read/ store a request
       Default: empty; autogenerated file below /var/tmp/http-cache
 
@@ -119,10 +350,10 @@ INSTRUCTION:
 
 - make the request
 
-    http.makeRequest [[METHOD] [URL] [BODY]]
-      The parameters are optional. Without parameter the rquest will be
+    http.makeRequest [[<METHOD>] ["<URL>"] ["<BODY>"]]
+      The parameters are optional. Without parameter the request will be
       started with given data in http.set* functions described above.
-      If minimum one pram is given then they are handled:
+      If minimum one param is given then they are handled:
         METHOD  optional: set a method (must be uppercase) - see http.setMethod
         URL     set a relative url - see http.setUrl
         BODY    optional: set a body - see http.setBody
@@ -176,7 +407,7 @@ INSTRUCTION:
 
 - import/ export
 
-      http.responseExport [FILE]
+      http.responseExport ["<FILE>"]
         dump the response data
         Without parameter it is written on STDOUT.
         You can set a filename to write it to a file.
@@ -187,7 +418,7 @@ INSTRUCTION:
         http.makeRequest "https://example.com/api/"
         http.responseExport /tmp/something_AUTOFILE_.txt
 
-      http.responseImport FILE
+      http.responseImport "<FILE>"
         Import an export file.
         To use the AUTOFILE mechanism from export set
         the url first.
@@ -195,12 +426,8 @@ INSTRUCTION:
         http.setFullUrl "https://example.com/api/"
         http.responseImport /tmp/something_AUTOFILE_.txt
 
-      http.responseDelete FILE
+      http.responseDelete "<FILE>"
         Delete a file after http.responseExport.
         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 → docs/50_Examples.md

@@ -164,3 +164,28 @@ http.setAuth
 http.makeRequest GET "api"
 http.makeRequest GET "app"
 ```
+
+## Gitlab access token
+
+Gitlab uses the value `PRIVATE-TOKEN: <token>` in the request header for authorization.
+Here we need `http.addHeader` to add a custom header line.
+
+```sh
+URL='https://gitlab.example.com/api/v4'
+TOKEN='<add-your-token-here>' # glpat-**********
+
+# ---------- init
+
+http.init
+http.addHeader "PRIVATE-TOKEN: $TOKEN"
+http.setBaseUrl "$URL"
+
+# ---------- Requests to api
+
+http.makeRequest /users
+http.getResponse | jq
+
+http.makeRequest /projects
+http.getResponse | jq
+
+```

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

@@ -4,7 +4,7 @@ List of all functions in alphabetic order
 
 ### http()
 
-[line: 95](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L95)
+[line: 96](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L96)
 
 ### http.addHeader()
 
@@ -16,7 +16,7 @@ Add a line to the request header
 
 ```
 
-[line: 681](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L681)
+[line: 682](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L682)
 
 ### http.dump()
 
@@ -28,7 +28,7 @@ no params
 
 ```
 
-[line: 576](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L576)
+[line: 577](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L577)
 
 ### http.flushCache()
 
@@ -40,7 +40,7 @@ no params
 
 ```
 
-[line: 841](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L841)
+[line: 842](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L842)
 
 ### http.getRequestAge()
 
@@ -55,7 +55,7 @@ returns integer  age of the response in sec
 
 ```
 
-[line: 423](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L423)
+[line: 424](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L424)
 
 ### http.getRequestTs()
 
@@ -69,7 +69,7 @@ returns string  the timestamp of the response
 
 ```
 
-[line: 409](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L409)
+[line: 410](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L410)
 
 ### http.getResponse()
 
@@ -83,7 +83,7 @@ returns string  the response body
 
 ```
 
-[line: 442](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L442)
+[line: 443](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L443)
 
 ### http.getResponseData()
 
@@ -97,7 +97,7 @@ returns string  the response data
 
 ```
 
-[line: 455](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L455)
+[line: 456](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L456)
 
 ### http.getResponseHeader()
 
@@ -111,7 +111,7 @@ returns string  the response header
 
 ```
 
-[line: 468](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L468)
+[line: 469](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L469)
 
 ### http.getResponseRaw()
 
@@ -125,7 +125,7 @@ no param
 
 ```
 
-[line: 481](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L481)
+[line: 482](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L482)
 
 ### http.getStatus()
 
@@ -137,7 +137,7 @@ no params
 
 ```
 
-[line: 492](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L492)
+[line: 493](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L493)
 
 ### http.getStatuscode()
 
@@ -149,7 +149,7 @@ no params
 
 ```
 
-[line: 505](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L505)
+[line: 506](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L506)
 
 ### http.help()
 
@@ -161,7 +161,7 @@ no params
 
 ```
 
-[line: 852](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L852)
+[line: 853](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L853)
 
 ### http.init()
 
@@ -174,7 +174,7 @@ function. It will reset all variables.
 
 ```
 
-[line: 116](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L116)
+[line: 117](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L117)
 
 ### http.isClientError()
 
@@ -186,7 +186,7 @@ no params
 
 ```
 
-[line: 554](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L554)
+[line: 555](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L555)
 
 ### http.isError()
 
@@ -198,7 +198,7 @@ no params
 
 ```
 
-[line: 543](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L543)
+[line: 544](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L544)
 
 ### http.isOk()
 
@@ -215,7 +215,7 @@ no params
 
 ```
 
-[line: 521](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L521)
+[line: 522](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L522)
 
 ### http.isRedirect()
 
@@ -227,7 +227,7 @@ no params
 
 ```
 
-[line: 532](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L532)
+[line: 533](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L533)
 
 ### http.isServerError()
 
@@ -239,7 +239,7 @@ no params
 
 ```
 
-[line: 565](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L565)
+[line: 566](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L566)
 
 ### http.loadcfg()
 
@@ -265,7 +265,7 @@ The function will then set the "internal" vars
 
 ```
 
-[line: 284](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L284)
+[line: 285](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L285)
 
 ### http.makeRequest()
 
@@ -287,7 +287,7 @@ This function does the following:
 
 ```
 
-[line: 168](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L168)
+[line: 169](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L169)
 
 ### http.quit()
 
@@ -309,7 +309,7 @@ no params
 
 ```
 
-[line: 251](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L251)
+[line: 252](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L252)
 
 ### http.responseDelete()
 
@@ -322,7 +322,7 @@ AUTOFILE functionality
 
 ```
 
-[line: 652](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L652)
+[line: 653](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L653)
 
 ### http.responseExport()
 
@@ -334,7 +334,7 @@ Export response to a file
 
 ```
 
-[line: 610](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L610)
+[line: 611](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L611)
 
 ### http.responseImport()
 
@@ -346,7 +346,7 @@ Import a former response from a file
 
 ```
 
-[line: 628](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L628)
+[line: 629](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L629)
 
 ### http.setAccept()
 
@@ -358,7 +358,7 @@ set Accept request header and override default
 
 ```
 
-[line: 692](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L692)
+[line: 693](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L693)
 
 ### http.setAuth()
 
@@ -371,7 +371,7 @@ Without given parameter, authentication is removed
 
 ```
 
-[line: 708](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L708)
+[line: 709](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L709)
 
 ### http.setAuthorization()
 
@@ -385,7 +385,7 @@ Without given parameter, authorization is removed
 
 ```
 
-[line: 725](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L725)
+[line: 726](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L726)
 
 ### http.setBaseUrl()
 
@@ -398,7 +398,7 @@ Remark: Then use http.setUrl to complet the url to request
 
 ```
 
-[line: 752](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L752)
+[line: 753](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L753)
 
 ### http.setBody()
 
@@ -410,7 +410,7 @@ Set body to send for PUTs and POSTs
 
 ```
 
-[line: 740](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L740)
+[line: 741](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L741)
 
 ### http.setCacheFile()
 
@@ -422,7 +422,7 @@ Set cache file
 
 ```
 
-[line: 830](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L830)
+[line: 831](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L831)
 
 ### http.setCacheTtl()
 
@@ -434,7 +434,7 @@ Set cache ttl in seconds
 
 ```
 
-[line: 819](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L819)
+[line: 820](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L820)
 
 ### http.setDebug()
 
@@ -446,11 +446,11 @@ Enable or disable debug mode
 
 ```
 
-[line: 764](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L764)
+[line: 765](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L765)
 
 ### http.setDocs()
 
-[line: 768](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L768)
+[line: 769](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L769)
 
 ### http.setFullUrl()
 
@@ -462,7 +462,7 @@ Set a full url to request
 
 ```
 
-[line: 790](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L790)
+[line: 791](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L791)
 
 ### http.setMethod()
 
@@ -474,7 +474,7 @@ Set the method to use; GET|POST|PUT|DELETE|...
 
 ```
 
-[line: 779](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L779)
+[line: 780](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L780)
 
 ### http.setUrl()
 
@@ -486,7 +486,7 @@ Complete the base url
 
 ```
 
-[line: 805](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L805)
+[line: 806](https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/blob/master/rest-api-client.sh#L806)
 
 - - -
 Generated with [Bashdoc](https://github.com/axelhahn/bashdoc) v0.6

docs/_index.md

 <html>
 <div class="hero">
     <h2>Bash REST API client</h2>
-    
+    A set of class like functions with a <code>http.</code> prefix.
 </div>
 </html>
 

docs/style.css

 /*
     override css elements of daux.io blue theme
-    version 2024-10-10
+    version 2024-10-23
 */
 :root {
     /* Axels Overrides */
@@ -35,6 +35,7 @@
     --axel_h3: #333;
     --axel_h3-bottom: 0px solid #ddd;
     --axel_h4: #444;
+    --axel_h5: #888;
     --axel_hero_bg: #f8f8f8;
     --axel_img-border: 2px dashed #ccc;
     --axel_nav-bg: #fcfcfc;
@@ -181,6 +182,13 @@ img{
 
 .s-content > h4 {
     color: var(--axel_h4);
+    font-size: 140%;
+    font-weight: bold;
+    margin: 2em 0;
+}
+
+.s-content > h5 {
+    color: var(--axel_h5);
     font-size: 135%;
     font-weight: bold;
     margin: 2em 0;

rest-api-client.sh

@@ -22,9 +22,10 @@
 # 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
+# 2024-10-23  v0.10 axel.hahn@unibe.ch      update help
 # ======================================================================
 
-  http_cfg__about="Bash REST API client v0.9"
+  http_cfg__about="Bash REST API client v0.10"
   typeset -i http_cfg__debug=0
   typeset -i http_cfg__cacheTtl=0
   http_cfg__cacheDir=/var/tmp/http-cache
@@ -867,7 +868,7 @@ INSTRUCTION:
 - Then you can run functions starting with "http."
 
     http.init
-      Start a new request. It resets internal vars of the last response
+      Start a new request. It resets internal vars of the last request
       (if there was one).
 
     http.setDebug 0|1
@@ -876,52 +877,54 @@ INSTRUCTION:
 
 - initialize a request
 
-    setAccept ACCEPT
+    setAccept "<ACCEPTHEADER>"
       Set authentication with user and password for basic auth
       Default: $http_req__accept
 
-    setAuth AUTH:PASSWORD
+    setAuth "<USER>:<PASSWORD>"
       Set authentication with user and password for basic auth
       Without given parameter, authentication is removed
 
-    setAuthorization TYPE TOKEN|HASH
+    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
+      2nd param is the token or hashed user+password
       Without given parameter, authorization is removed
 
-    http.setBody DATA
+    http.setBody "<DATA>"
       set a body for POST/ PUT requests.
 
-    http.setBaseUrl URL
+    http.setBaseUrl "<URL>"
       Set a base url to an api.
       renmark:
       Use http.setUrl to built a complete url.
 
-    http.setDocs URL
+    http.setDocs "<URL>"
+      Set a docs url. If set it will be shown as additional hint when a 
+      request fails.
 
-    http.setMethod METHOD
+    http.setMethod "<METHOD>"
       Set a http method. Use an uppercase string for GET|POST|PUT|DELETE|...
 
-    http.setFullUrl URL
+    http.setFullUrl "<URL>"
       Set a complete url for a request.
 
-    http.setUrl REQUEST?QUERY
+    http.setUrl "<REQUEST?QUERY>"
       Set a relative url for a request.
       This requires to use http.setBaseUrl before.
 
-    http.addHeader HEADER_LINE
+    http.addHeader "<HEADER_LINE>"
       Add a header line to the request.
       This command can be repeated multiple times.
 
 - caching functions
 
-    http.setCacheTtl SECONDS
+    http.setCacheTtl <SECONDS>
       Enable caching with values > 0
       Remark: only GET requests will be cached.
       Default: 0 (no caching)
 
-    http.setCacheFile FILENAME
+    http.setCacheFile "<FILENAME>"
       Set a file where to read/ store a request
       Default: empty; autogenerated file below $http_cfg__cacheDir
 
@@ -930,10 +933,10 @@ INSTRUCTION:
 
 - make the request
 
-    http.makeRequest [[METHOD] [URL] [BODY]]
-      The parameters are optional. Without parameter the rquest will be
+    http.makeRequest [[<METHOD>] ["<URL>"] ["<BODY>"]]
+      The parameters are optional. Without parameter the request will be
       started with given data in http.set* functions described above.
-      If minimum one pram is given then they are handled:
+      If minimum one param is given then they are handled:
         METHOD  optional: set a method (must be uppercase) - see http.setMethod
         URL     set a relative url - see http.setUrl
         BODY    optional: set a body - see http.setBody
@@ -987,7 +990,7 @@ INSTRUCTION:
 
 - import/ export
 
-      http.responseExport [FILE]
+      http.responseExport ["<FILE>"]
         dump the response data
         Without parameter it is written on STDOUT.
         You can set a filename to write it to a file.
@@ -998,7 +1001,7 @@ INSTRUCTION:
         http.makeRequest "https://example.com/api/"
         http.responseExport /tmp/something_AUTOFILE_.txt
 
-      http.responseImport FILE
+      http.responseImport "<FILE>"
         Import an export file.
         To use the AUTOFILE mechanism from export set
         the url first.
@@ -1006,7 +1009,7 @@ INSTRUCTION:
         http.setFullUrl "https://example.com/api/"
         http.responseImport /tmp/something_AUTOFILE_.txt
 
-      http.responseDelete FILE
+      http.responseDelete "<FILE>"
         Delete a file after http.responseExport.
         It is useful if you use the AUTOFILE mechanism.