Skip to content
Snippets Groups Projects
Select Git revision
  • f56b8a8fe0fc47b82b1ca6390acf3c3f44d71ca3
  • master default protected
2 results

40_Usage.md

Blame
  • Hahn Axel (hahn)'s avatar
    Hahn Axel (hahn) authored
    f56b8a8f
    History

    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 ":". 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'

    or

    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.