Usage

Initialize
Make a request
- Request multiple urls
- Other functions
Get response
Get status
Caching
Import/ Export
Help: list all functions

Initialize

Source the script

You must source the http.class.sh. Then its functions are usable in the current process. The “methods” start with “http” dot “[method]”.

#!/bin/bash
cd "$( dirname "$0" )" || exit
. ./http.class.sh || exit 1

Initialize a new request

Start a new request. It resets internal vars of the last request.

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.setMethod <METHOD> Set a http method. Use an uppercase string for GET|POST|PUT|DELETE|… (any method)
http.setCA <FILE> Set a ca cert file (it results in –cacert <file>). Without parameter this flag will be removed.
http.setDocs <URL> Set a docs url. If set it will be shown as additional hint when a request fails.
http.setInsecure 1 Do not verify SSL certificate (it results in -k parameter not recommended). Without parameter this flag will be removed.
http.addHeader <HEADER_LINE> Add a header line to the request. This command can be repeated multInsecure 1
http.addCurlparam <parameter> Add any mising curl parameter when making the requests. This command can be repeated multiple times.

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.

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'

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

http.makeRequest "https://www.example.com/userinfos"

use http.setFullUrl

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:

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:

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

#
# step one: source the shell script
#
$ . ./http.class.sh

#
# then use its functions.
#
$ http.help

Bash REST API client v0.11

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.setCA "<FILE>"
      Set CA file to verify the server certificate. 
      Default: [empty] = use system defaults
      Without parameter the cafile is removed

    http.setDocs "<URL>"
      Set a docs url. If set it will be shown as additional hint when a 
      request fails.

    http.setInsecure 1
      Set insecure flag by giving any non empty value. 
      Default: [empty] = secure requests
      Without parameter the insecure flag is removed

    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 to add multiple headers.

    http.addCurlparam "<CURL_PARAMETER>"
      Add any missing parameter for curl requestst.
      This command can be repeated multiple times to add multiple prameters.
      You also can add multiple parameters with one command.

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

Table of Contents

#Initialize

#Source the script

#Initialize a new request

#Define a request

#Authentication

#Basic authentication

#Authorization header

#Other Authorizations

#Set url

#Other funtions

#Make a request

#Request multiple urls

#Other functions

#Get response

#Get status

#Caching

#Import/ Export

#Help: list all functions

Initialize

Source the script

Initialize a new request

Define a request

Authentication

Basic authentication

Authorization header

Other Authorizations

Set url

Other funtions

Make a request

Request multiple urls

Other functions

Get response

Get status

Caching

Import/ Export

Help: list all functions