f634c352b8dab7b8c2c263b49706144ad05a784f to 250dc9d7d2729780e17bdb22adbcdd8c946643fd · IML Open Source / bash-rest-api-client

README.md

+3
−2

Original line number
Diff line number
Diff line

# 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

+2
−2

Original line number
Diff line number
Diff line

@@ -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.md0 → 100644

+51
−0

Original line number
Diff line number
Diff line

## 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

+433
−0

Original line number
Diff line number
Diff line

## 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

+25
−0

Original line number
Diff line number
Diff line

@@ -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

+37
−37

Original line number
Diff line number
Diff line

@@ -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

+1
−1

Original line number
Diff line number
Diff line

<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

+9
−1

Original line number
Diff line number
Diff line

/*

    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

+24
−21

Original line number
Diff line number
Diff line

@@ -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.

Compare revisions

Source

Target

Commits on Source 5

Files

README.md

docs/10_Introduction.md

docs/30_Quickstart.md

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

docs/40_Examples.md→docs/50_Examples.md

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

docs/_index.md

docs/style.css

rest-api-client.sh