diff --git a/README.md b/README.md
index 0bfbdb1892809b5f7dc9dfde866a411fe58f520b..3e85997fded3b6751fb14ed59368499116a387fd 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
# 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
diff --git a/docs/10_Introduction.md b/docs/10_Introduction.md
index 4c566a394130d83c5bc7ed426e0422c2d0aad94a..84d7c2be1d146d64503fa4f67e17e8e3901eaa32 100644
--- a/docs/10_Introduction.md
+++ b/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
diff --git a/docs/30_Quickstart.md b/docs/30_Quickstart.md
new file mode 100644
index 0000000000000000000000000000000000000000..132394af1f9720c0c3d289b10d9687410114749f
--- /dev/null
+++ b/docs/30_Quickstart.md
@@ -0,0 +1,51 @@
+## 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.
+
+
diff --git a/docs/30_Usage.md b/docs/30_Usage.md
deleted file mode 100644
index 33d407e93c3cd0fe08e4b647d182711c865a5e4c..0000000000000000000000000000000000000000
--- a/docs/30_Usage.md
+++ /dev/null
@@ -1,206 +0,0 @@
-## 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]".
-
-### 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.
-
-```text
-#
-# step one: source the shell script
-#
-$ . ./rest-api-client.sh
-
-#
-# then use its functions.
-#
-$ http.help
-
-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>
-Docs: <https://os-docs.iml.unibe.ch/bash-rest-api-client/>
-License: GNU GPL 3
-
-
-INSTRUCTION:
-
-- Source the file once
-- Then you can run functions starting with "http."
-
- http.init
- Start a new request. It resets internal vars of the last response
- (if there was one).
-
- http.setDebug 0|1
- Enable or disable debugging infos during processing. It is written
- to STDERR.
-
-- initialize a request
-
- setAccept ACCEPT
- Set authentication with user and password for basic auth
- Default: application/json
-
- 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.
-
- http.setBaseUrl URL
- Set a base url to an api.
- renmark:
- Use http.setUrl to built a complete url.
-
- http.setDocs URL
-
- http.setMethod METHOD
- Set a http method. Use an uppercase string for GET|POST|PUT|DELETE|...
-
- http.setFullUrl URL
- Set a complete url for a request.
-
- http.setUrl REQUEST?QUERY
- Set a relative url for a request.
- This requires to use http.setBaseUrl before.
-
- http.addHeader HEADER_LINE
- Add a header line to the request.
- This command can be repeated multiple times.
-
-- caching functions
-
- http.setCacheTtl SECONDS
- Enable caching with values > 0
- 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
-
-- make the request
-
- http.makeRequest [[METHOD] [URL] [BODY]]
- The parameters are optional. Without parameter the rquest will be
- started with given data in http.set* functions described above.
- If minimum one pram 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
-
- 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
-
-- handle response
-
- http.getResponse
- Get the Response Body
-
- http.getResponseData
- Get Meta infos from curl
-
- http.getResponseHeader
- Get The http reponse header
-
-- check http status code
-
- http.getStatus
- Get the http status as string Ok|Redirect|Error
-
- http.getStatuscode
- Get the http status code of a request as 3 digit integer
-
- 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
-
- http.getRequestAge
- Get the age of the request in seconds.
- Remark: This function is useful after an import
- see http.responseImport.
-
- http.getRequestTs
- Get the Unix timestamp of the request
-
-- import/ export
-
- 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.
- The filename can contain "AUTOFILE" this string
- will be replaced with a uniq string.
- (requires sha1sum and a set url)
- 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
- the url first.
- Example:
- http.setFullUrl "https://example.com/api/"
- http.responseImport /tmp/something_AUTOFILE_.txt
-
- 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.
diff --git a/docs/40_Usage.md b/docs/40_Usage.md
new file mode 100644
index 0000000000000000000000000000000000000000..6cb16b612a4179d002a1980b7ca89c933f8febc9
--- /dev/null
+++ b/docs/40_Usage.md
@@ -0,0 +1,433 @@
+## 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
+
+Start a new request. It resets internal vars of the last request.
+
+```sh
+http.init
+```
+
+### Define a request
+
+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.
+
+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
+
+### Request multiple urls
+
+When performing multiple requests to the same backend use `http.setBaseUrl <URL>` to set a base url first.
+
+```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
+#
+# step one: source the shell script
+#
+$ . ./rest-api-client.sh
+
+#
+# then use its functions.
+#
+$ http.help
+
+Bash REST API client v0.10
+
+This is a bash solution to script REST API calls.
+
+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
+
+
+INSTRUCTION:
+
+- Source the file once
+- Then you can run functions starting with "http."
+
+ http.init
+ Start a new request. It resets internal vars of the last request
+ (if there was one).
+
+ http.setDebug 0|1
+ Enable or disable debugging infos during processing. It is written
+ to STDERR.
+
+- initialize a request
+
+ setAccept "<ACCEPTHEADER>"
+ Set authentication with user and password for basic auth
+ Default: application/json
+
+ setAuth "<USER>:<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 hashed user+password
+ Without given parameter, authorization is removed
+
+ http.setBody "<DATA>"
+ set a body for POST/ PUT requests.
+
+ http.setBaseUrl "<URL>"
+ Set a base url to an api.
+ renmark:
+ Use http.setUrl to built a complete url.
+
+ http.setDocs "<URL>"
+ 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|...
+
+ http.setFullUrl "<URL>"
+ Set a complete url for a request.
+
+ http.setUrl "<REQUEST?QUERY>"
+ Set a relative url for a request.
+ This requires to use http.setBaseUrl before.
+
+ http.addHeader "<HEADER_LINE>"
+ Add a header line to the request.
+ This command can be repeated multiple times.
+
+- caching functions
+
+ http.setCacheTtl <SECONDS>
+ Enable caching with values > 0
+ 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
+
+- make the request
+
+ 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
+
+ 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
+
+- handle response
+
+ http.getResponse
+ Get the Response Body
+
+ http.getResponseData
+ Get Meta infos from curl
+
+ http.getResponseHeader
+ Get The http reponse header
+
+- check http status code
+
+ http.getStatus
+ Get the http status as string Ok|Redirect|Error
+
+ http.getStatuscode
+ Get the http status code of a request as 3 digit integer
+
+ 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
+
+ http.getRequestAge
+ Get the age of the request in seconds.
+ Remark: This function is useful after an import
+ see http.responseImport.
+
+ http.getRequestTs
+ Get the Unix timestamp of the request
+
+- import/ export
+
+ 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.
+ The filename can contain "AUTOFILE" this string
+ will be replaced with a uniq string.
+ (requires sha1sum and a set url)
+ 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
+ the url first.
+ Example:
+ http.setFullUrl "https://example.com/api/"
+ http.responseImport /tmp/something_AUTOFILE_.txt
+
+ http.responseDelete "<FILE>"
+ Delete a file after http.responseExport.
+ It is useful if you use the AUTOFILE mechanism.
+
+```
diff --git a/docs/40_Examples.md b/docs/50_Examples.md
similarity index 89%
rename from docs/40_Examples.md
rename to docs/50_Examples.md
index 785e054538822f1223d295cd05ddedc00b577e5f..1a8c8577d912a6d17092f0f1ab7d82a2705fca56 100644
--- a/docs/40_Examples.md
+++ b/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
+
+```
diff --git a/docs/99_Functions/rest-api-client.sh.md b/docs/99_Functions/rest-api-client.sh.md
index c6cd54d6eff73b0a4e60c58b4ac3fb75428b494d..7ee93f17da7a40f69796258c2b2cbdf95d19a40a 100644
--- a/docs/99_Functions/rest-api-client.sh.md
+++ b/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
diff --git a/docs/_index.md b/docs/_index.md
index 2300b3ad7ebfe98cdcef1677fa3e1cec39c5dc8c..2801ff2997b37f07936c4de18e998d96e6b68ed2 100644
--- a/docs/_index.md
+++ b/docs/_index.md
@@ -1,7 +1,7 @@
<html>
<div class="hero">
<h2>Bash REST API client</h2>
-
+ A set of class like functions with a <code>http.</code> prefix.
</div>
</html>
diff --git a/docs/style.css b/docs/style.css
index 3a46f4d565a8af02ae02e510e1a368c53bed83f3..171dbfba84ec6ccc177373a67c49b464272be7a2 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -1,6 +1,6 @@
/*
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;
diff --git a/rest-api-client.sh b/rest-api-client.sh
index ab6e9e48f01647e556889a9301b24caadf06a9be..0ac9e9d0a66aedb0a7ea3eb973d33e90988245ae 100644
--- a/rest-api-client.sh
+++ b/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.