From de15187863a4cfb04db671892a194862176d207f Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@unibe.ch>
Date: Wed, 9 Oct 2024 14:04:51 +0200
Subject: [PATCH] update readme and docs

---
 README.md                               | 25 +++++++++++-------
 docs/10_Installation.md                 | 19 --------------
 docs/10_Introduction.md                 | 21 +++++++++++++++
 docs/20_Installation.md                 | 26 ++++++++++++++++++
 docs/{20_Usage.md => 30_Usage.md}       | 29 +++++++++++++++++---
 docs/{30_Examples.md => 40_Examples.md} | 35 ++++++++++++++++++++++---
 docs/_index.md                          | 34 ++++++++----------------
 7 files changed, 130 insertions(+), 59 deletions(-)
 delete mode 100644 docs/10_Installation.md
 create mode 100644 docs/10_Introduction.md
 create mode 100644 docs/20_Installation.md
 rename docs/{20_Usage.md => 30_Usage.md} (84%)
 rename docs/{30_Examples.md => 40_Examples.md} (81%)

diff --git a/README.md b/README.md
index e984b10..4ec4a68 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# REST API CLIENT
+# Bash REST API client
 
 This is a bash solution to script REST API calls.
 
@@ -12,16 +12,21 @@ The specialties of this component are
 * 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
 
-Source: <https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client>
+👤 Author: Axel Hahn; Institute for Medical Education; University of Bern \
+📄 Source: <https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client> \
+📜 License: GNU GPL 3.0 \
+📗 Docs: <https://os-docs.iml.unibe.ch/bash-rest-api-client/>
 
-License: GNU GPL 3
 
-## Requirements
+```text
+http.init
+http.makeRequest 'http://www.example.com/'
+```
 
-* Bash as shell (runs on Linux - or with Cygwin or other Bash implementations on MS Windows too.)
-* Curl must be in the path
-* optional: sha1sum (for export function with autogenerated filenames only)
+This stores the response in a variable and has no output.
+Now you can get its data, eg
 
----
-
-[Installation](docs/10_Installation.md) | [Usage](docs/20_Usage.md) | [Examples](docs/30_Examples.md)
\ No newline at end of file
+* 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
diff --git a/docs/10_Installation.md b/docs/10_Installation.md
deleted file mode 100644
index 1e67cab..0000000
--- a/docs/10_Installation.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Download
-
-
-Download the archive i.e. as zip:
-
-https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/archive/master/bash-rest-api-client-master.zip
-
-(see other formats at the download button on https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client)
-
-# OR: Git clone
-
-```sh
-git clone https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client.git
-```
-
-# Copy somewhere
-
-Copy the file `rest-api-client.sh` anywhere you want.
-If you need it in a single script then copy it to its directory. If you need it more often then copy it to a folter of your PATH environment.
diff --git a/docs/10_Introduction.md b/docs/10_Introduction.md
new file mode 100644
index 0000000..fbdf506
--- /dev/null
+++ b/docs/10_Introduction.md
@@ -0,0 +1,21 @@
+## Introduction
+
+### Description
+
+This is a bash solution to script REST API calls.
+
+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
+* 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
+
+### Requirements
+
+* Bash as shell (runs on Linux - or with Cygwin or other Bash implementations on MS Windows too.)
+* Curl must be in the path
+* optional: sha1sum (for export function with autogenerated filenames only)
diff --git a/docs/20_Installation.md b/docs/20_Installation.md
new file mode 100644
index 0000000..4dc5de1
--- /dev/null
+++ b/docs/20_Installation.md
@@ -0,0 +1,26 @@
+## Installation
+
+### Get all files
+
+#### Git clone
+
+```sh
+git clone https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client.git
+```
+
+#### Download
+
+Download the archive i.e. as zip:
+
+<https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/archive/master/bash-rest-api-client-master.zip>
+
+(see other formats at the download button on <https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client>)
+
+#### Copy shell script somewhere
+
+Copy the file `rest-api-client.sh` anywhere you need it.
+If you need it in a single script then copy it to its directory. If you need it more often then copy it to a folter of your PATH environment.
+
+### Get the script only
+
+`wget https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client/-/raw/master/rest-api-client.sh`
diff --git a/docs/20_Usage.md b/docs/30_Usage.md
similarity index 84%
rename from docs/20_Usage.md
rename to docs/30_Usage.md
index 591344e..d421e15 100644
--- a/docs/20_Usage.md
+++ b/docs/30_Usage.md
@@ -7,7 +7,7 @@ The "methods" start with "http" dot "[method]".
 
 You should start with *http.help* to get an overwiew.
 
-```sh
+```text
 #
 # step one: source the shell script
 #
@@ -18,6 +18,15 @@ $ . ./rest-api-client.sh
 #
 $ http.help
 
+
+Bash REST API client v0.8
+
+This is a bash solution to script REST API calls.
+
+Source:https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client
+License: GNU GPL 3
+
+
 INSTRUCTION:
 
 - Source the file once
@@ -31,11 +40,19 @@ INSTRUCTION:
       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
+      Set authentication with user and password for basic auth
+
+    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
 
     http.setBody DATA
       set a body for POST/ PUT requests.
@@ -57,6 +74,10 @@ INSTRUCTION:
       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
@@ -103,7 +124,7 @@ INSTRUCTION:
         Get the http status as string Ok|Redirect|Error
 
       http.getStatuscode
-        Get the http status code of a request as integer
+        Get the http status code of a request as 3 digit integer
 
       http.isOk
         Check if the http response code is a 2xx
diff --git a/docs/30_Examples.md b/docs/40_Examples.md
similarity index 81%
rename from docs/30_Examples.md
rename to docs/40_Examples.md
index c0ca4d1..e91c6e7 100644
--- a/docs/30_Examples.md
+++ b/docs/40_Examples.md
@@ -1,4 +1,4 @@
-# Preparation
+## Preparation
 
 A required step is sourcing the script to make the http.* function available in the current shell.
 
@@ -9,7 +9,7 @@ A required step is sourcing the script to make the http.* function available in
 
 Then you can follow the examples.
 
-# A first example
+## A first example
 
 This is quick introduction: we make a request and have a look to a few results.
 
@@ -67,7 +67,7 @@ url_effective:http://www.iml.unibe.ch/
 
 ```
 
-# Icinga2 API
+## Icinga2 API
 
 In that example we have a config for an api access with url, user and password.
 The docs url is not required for functionality. It will be shown on errors.
@@ -113,3 +113,32 @@ if [ $? -ne 0 ]; then
 fi
 echo "OK, ${myHost} was found."
 ```
+
+## Authentication with JWT token
+
+The snippet shows how to fetch a token first that will be added to be used in all following requests.
+
+```sh
+# ---------- settings
+URL=https://www.example.com/
+USER=...
+PASSWORD=...
+
+# ---------- init
+http.init
+http.setBaseUrl "${URL}"
+
+# ---------- 1st request: get a token
+http.setAuth "${USER}:${PASSWORD}"
+http.makeRequest GET "token"
+
+# fetch token 
+ACCESS_TOKEN=$(http.getResponse | jq -r .access_token)
+
+# Set token for authorization
+http.setAuthorization "Bearer ${ACCESS_TOKEN}"
+
+# ---------- Requests to app or api
+http.makeRequest GET "api"
+http.makeRequest GET "app"
+```
diff --git a/docs/_index.md b/docs/_index.md
index 5541390..2300b3a 100644
--- a/docs/_index.md
+++ b/docs/_index.md
@@ -1,23 +1,11 @@
-# Description
-
-This is a bash solution to script REST API calls.
-
-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
-* 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
-
-Source: https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client
-
-License: GNU GPL 3
-
-# Requirements
-
-* Bash as shell (runs on Linux - or with Cygwin or other Bash implementations on MS Windows too.)
-* Curl must be in the path
-* optional: sha1sum (for export function with autogenerated filenames only)
+<html>
+<div class="hero">
+    <h2>Bash REST API client</h2>
+    
+</div>
+</html>
+
+👤 Author: Axel Hahn; Institute for Medical Education; University of Bern \
+📄 Source: <https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client> \
+📜 License: GNU GPL 3.0 \
+📗 Docs: <https://os-docs.iml.unibe.ch/bash-rest-api-client/>
-- 
GitLab