readme.md

REST API CLIENT

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

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)

Installation

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

$ git clone https://git-repo.iml.unibe.ch/iml-open-source/bash-rest-api-client.git

Copy the rest-api-client.sh anywhere you want.

Usage

You must source the rest-api-client.sh. Then its functions are usable in the current process. The "methods" start with "http" dot "[method]".

You should start with http.help to get an overwiew.

#
# step one: source the shell script
#
$ . ./rest-api-client.sh

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

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

    setAuth AUTH:PASSWORD
      set authentication

    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.

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