From 15caa886a2748e9c4311cfdd87dddcb0768f84e4 Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@unibe.ch>
Date: Wed, 23 Oct 2024 15:01:06 +0200
Subject: [PATCH] update docs and help
---
docs/30_Quickstart.md | 51 +++
docs/30_Usage.md | 255 --------------
docs/40_Usage.md | 433 ++++++++++++++++++++++++
docs/{40_Examples.md => 50_Examples.md} | 0
docs/99_Functions/rest-api-client.sh.md | 74 ++--
docs/style.css | 10 +-
rest-api-client.sh | 45 +--
7 files changed, 554 insertions(+), 314 deletions(-)
create mode 100644 docs/30_Quickstart.md
delete mode 100644 docs/30_Usage.md
create mode 100644 docs/40_Usage.md
rename docs/{40_Examples.md => 50_Examples.md} (100%)
diff --git a/docs/30_Quickstart.md b/docs/30_Quickstart.md
new file mode 100644
index 0000000..132394a
--- /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 ed254ae..0000000
--- a/docs/30_Usage.md
+++ /dev/null
@@ -1,255 +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.
-
-## 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>"`. 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 hased "<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 Authorizatins
-
-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.
diff --git a/docs/40_Usage.md b/docs/40_Usage.md
new file mode 100644
index 0000000..6cb16b6
--- /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 100%
rename from docs/40_Examples.md
rename to docs/50_Examples.md
diff --git a/docs/99_Functions/rest-api-client.sh.md b/docs/99_Functions/rest-api-client.sh.md
index c6cd54d..7ee93f1 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/style.css b/docs/style.css
index 3a46f4d..171dbfb 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 ab6e9e4..0ac9e9d 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.
--
GitLab