esi-lcurl-http-client

  • HTTP Client to perform HTTP requests using the lcurl library.

  • Using lcurl library which documentation can be found here.

  • Supports HTTPS requests via proxy using optional proxy credentials.

Available functions

name type description

NEW

function

Creates a new httpClient object with optional options

ISSUCCESS

method

Return true if HTTP response code is between 200 and 299.

HEADERVALUEBYNAME

method

Fetching a header value by the name case-insensitive.

REQUEST

method

Generic method to send out a HTTP Request.

DELETE

method

Sends out a HTTP DELETE Request.

GET

method

Sends out a HTTP GET Request.

HEAD

method

Sends out a HTTP HEAD Request.

OPTIONS

method

Sends out a HTTP OPTIONS Request.

PATCH

method

Sends out a HTTP PATCH Request.

POST

method

Sends out a HTTP POST Request.

PUT

method

Sends out a HTTP PUT Request.

BASE64 (*)

method

Encodes string to Base64 string.

UNBASE64 (*)

method

Decodes Base64 string.

(*) Obsolete Base64 methods, use syslib.debase64 & syslib.enbase64 instead.

Examples Index

Request using Proxy

Documentation

NEW

NEW(options)

Create a new instance of the HTTPClient with options.

Supported options:

field type description example

httpauth (*)

string

HTTP server authentication method

'NTLM'

proxy

string

Hostname of the proxy

'proxy.company.com'

proxyCred

string

Username and password

'username:password'

ssl_verifypeer (**)

boolean

Check peer certificate

true

timeout

number

HTTP request timeout in seconds

10

username

string

Used in combination of httpauth

'jane-doe'

password

string

Used in combination of httpauth

'my-secret'

(*) Only NTLM is supported. Others methods can be achieved by setting the headers directly.

(**) If you don’t want to check peer certificate, set ssl_verifypeer to false or leave it nil.

Example of setting options when using a proxy server:

local options = {
    proxy = 'proxy.company.com',
    proxyCred = 'username:password',
    ssl_verifypeer = true
}

Usage:

local HTTPClient = require('esi-lcurl-http-client')
local options = {}
local httpClient = HTTPClient.NEW(options)

ISSUCCESS

ISSUCCESS(code)

Return true if HTTP response code is between 200 and 299.

if httpClient:ISSUCCESS(res.code) then
end

BASE64

BASE64(str,…​)

Encodes string to Base64 string.

UNBASE64

UNBASE64(b64Str)

Decodes Base64 string.

HEADERVALUEBYNAME

HEADERVALUEBYNAME(headers, name)

Fetching a header value by the name case-insensitive.

local value = httpClient:HEADERVALUEBYNAME(res.headers, 'Content-Type')

RESPONSE OBJECT

The requests returns a Lua table which includes:

field type description

ok

boolean

true if the request was successfully sent

code

number

HTTP response status codes

headers

table

Response headers

data

nil

No data returned

string

Can be anything

table

In case the response Content-Type is application/json

REQUEST

REQUEST(method, url, headers, reqData)

Sends out a HTTP Request.

Parameters:

method

like 'GET', 'POST', etc. Can also be a table contain the arguments as fields.

url

string containing the URL.

headers

(optional) table.

reqData

(optional) Request Data can be a string or a table.

Returns

table with res.ok, res.code (HTTP Response Codes) and optional res.data and res.headers

Usage:

local url = 'http://inmationwebapi.company.com:8002/api/checkstatus'
local res = httpClient:REQUEST('GET', url)
return res.ok, res.code, res.data, res.headers

DELETE

DELETE(url, headers, body)

Sends out a HTTP DELETE Request.

Parameters:

url

string containing the URL.

headers

(optional) table.

reqData

(optional) Request Data can be a string or a table.

Returns

table with res.ok, res.code (HTTP Response Codes) and optional res.data and res.headers

Usage:

local res = httpClient:DELETE(url)
return res.ok, res.code, res.data, res.headers

GET

GET(url, headers)

Sends out a HTTP GET Request.

Parameters:

url

string containing the URL.

headers

(optional) table.

Returns

table with res.ok, res.code (HTTP Response Codes) and optional res.data and res.headers

Usage:

local url = 'http://inmationwebapi.company.com:8002/api/checkstatus'
local res = httpClient:GET(url)
return res.ok, res.code, res.data, res.headers

HEAD(url, headers)

Sends out a HTTP HEAD Request which is a GET without response body.

Parameters:

url

string containing the URL.

headers

(optional) table.

Returns

table with res.ok, res.code (HTTP Response Codes) and optional res.data and res.headers

Usage:

local url = 'http://inmationwebapi.company.com:8002/api/checkstatus'
local res = httpClient:HEAD(url)
return res.ok, res.code, res.headers

OPTIONS

OPTIONS(url, headers, reqData)

Sends out a HTTP OPTIONS Request.

Parameters:

url

string containing the URL.

headers

(optional) table.

reqData

(optional) Request Data can be a string or a table.

Returns

table with res.ok, res.code (HTTP Response Codes) and optional res.data and res.headers

Usage:

local res = httpClient:OPTIONS(url)
return res.ok, res.code, res.data, res.headers

PATCH

PATCH(url, headers, reqData)

Sends out a HTTP PATCH Request.

Parameters:

url

string containing the URL.

headers

(optional) table.

reqData

(optional) Request Data can be a string or a table.

Returns | table with res.ok, res.code (HTTP Response Codes) and optional res.data and res.headers

Usage:

local reqData = {
msg = "Hello World!"
}
local res = httpClient:PATCH(url, {}, reqData)
return res.ok, res.code, res.data, res.headers

POST

POST(url, headers, reqData)

Sends out a HTTP POST Request.

Parameters:

url

string containing the URL.

headers

(optional) table.

reqData

(optional) Request Data can be a string or a table.

Returns

table with res.ok, res.code (HTTP Response Codes) and optional res.data and res.headers

Usage:

local reqData = {
msg = "Hello World!"
}
local res = httpClient:POST(url, {}, reqData)
return res.ok, res.code, res.data, res.headers

PUT

PUT(url, headers, reqData)

Sends out a HTTP PUT Request.

Parameters:

url

string containing the URL.

headers

(optional) table.

reqData

(optional) Request Data can be a string or a table.

Returns

table with res.ok, res.code (HTTP Response Codes) and optional res.data and res.headers

Usage:

local reqData = {
msg = "Hello World!"
}
local res = httpClient:PUT(url, {}, reqData)
return res.ok, res.code, res.data, res.headers

Examples

Request using Proxy

Making a HTTP request using a proxy server with authentication.

local HTTPClient = require('esi-lcurl-http-client')

local options = {
    proxy = 'proxy.company.com',
    proxyCred = 'username:password'
}

local httpClient = HTTPClient.NEW(options)

local url = "http://inmationwebapi.company.com:8002/api/checkstatus"
local res = httpClient:GET(url)

Compression

Handle responses with a specific Content-Encoding. In this example deflate.

Library LibDeflate can be found on GitHub.

local HTTPClient = require('esi-lcurl-http-client')
local LibDeflate = require("LibDeflate")

local httpClient = HTTPClient.NEW()

httpClient.ONENCODEDRESPONSEDATA = function(encoded, encoding)
    if encoding == 'deflate' then
        local decompress_deflate = encoded
        local decompressed = nil
        repeat
            decompress_deflate = LibDeflate:DecompressDeflate(decompress_deflate)
            if decompress_deflate ~= nil then
                decompressed = decompress_deflate
            end
        until(decompress_deflate == nil)
        return decompressed
    end
    error(("Unsupported encoding: '%s'"):format(encoding))
end