http

Summit http request library.

Classes

Name Summary
HttpResponse

An object representing a response from an HTTP request

Functions

Name Summary
get

HTTP GET request

post

HTTP POST request

put

HTTP PUT request

urlencode

URL encodes the provided data.

Classes : http

HttpResponse

An object representing a response from an HTTP request

Each of the HTTP methods in this library returns an HttpResponse object, which contains information about the request and response. This object cannot be instantiated directly, but is returned by the get, post, and put methods in this library.

Fields
Name Type Summary
url

string

The URL of the request

headers

table

The headers as returned by the remote server

content

string

The content of the response as a string

data

string

The parsed content of the response; currently, this uses a text parser so it will just be a string

statusCode

integer

HTTP Status Code of the response

reason

string

Reason for the status code returned

Functions : http

get(url, options)

HTTP GET request Make a GET request to the provided URL with the provided params. The URL should include the protcol (e.g. http, https)

Parameters
Name Type Default Summary

url

string

String of url to make request to

options

table

Parameter: options
Name Type Default Summary

basic_auth

table

nil

Table containing {<username>, <password>} for HTTP Basic Auth

data

table

{}

Table of key/value pairs to be sent as params with the request.

headers

table

{}

Table of key/value pairs to be sent as request headers

timeout

float

30

Request timeout. This is not a time limit on the entire reponse download; this only applies if the remote server does not issue any response at all for the specified number of seconds.

Returns
Type Summary

HttpResponse or nil

Table of information about the response (see link), or nil if an error occurred

nil or string

nil if successful, otherwise a description of the error

Usage
local http = require("summit.http")
local auth = {'testuser@example.com', 'password123'}
local res, err = http.get('http://example.com/api', {data={name='Tom', age=25}, headers={["Example-Header"]='example/header'}, basic_auth=auth})
print(res.url) -- 'http://example.com/api?name=Tom&age=25'
print(res.headers) -- e.g. {'content-length': '3', ...}
print(res.content) -- e.g. 'ok'
print(res.statusCode) -- e.g. 200
print(res.reason) -- e.g. 'OK'

local my_api_key, my_api_secret = "API_KEY", "API_SECRET"  -- Keys you have generated for your account.
local res, err = http.get('https://api.us1.corvisa.io/domain', {basic_auth={my_api_key, my_api_secret}})
if not err then
  local response_data = json:decode(res.content)
  local sip_domain = response_data.data[1].sip_domain
  print("My sip domain is: "..tostring(sip_domain))
end

post(url, options)

HTTP POST request Make a POST request to the provided URL with the provided params. The URL should include the protcol (e.g. http, https)

Parameters
Name Type Default Summary

url

string

String of url to make request to

options

table

Parameter: options
Name Type Default Summary

basic_auth

table

nil

Table containing {<username>, <password>} for HTTP Basic Auth

data

table

{}

Table of key/value pairs to be sent as data with the request. It can also be raw data like a string or a RecordingResult

files

table

{}

Table of filename/filehandle pairs to be sent as file encoded objects with the request.

headers

table

{}

Table of key/value pairs to be sent as request headers.

timeout

float

30

Request timeout. This is not a time limit on the entire reponse download; this only applies if the remote server does not issue any response at all for the specified number of seconds.

Returns
Type Summary

HttpResponse or nil

Table of information about the response (see link), or nil if an error occurred

nil or string

nil if successful, otherwise a description of the error

Usage
local http = require("summit.http")
local asset = require("summit.asset")
local post_file = asset("post_file.txt")
local auth = {'testuser@example.com', 'password123'}
local res, err = http.post('http://example.com/api', {data={name='Tom', age=25}, headers={["Example-Header"]='example/header'}, files={post_file=post_file}, basic_auth=auth})
print(res.url) -- 'http://example.com/api'
print(res.headers) -- e.g. {'content-length': '3', ...}
print(res.content) -- e.g. 'ok'
print(res.statusCode) -- e.g. 200
print(res.reason) -- e.g. 'OK'
...
-- Get a voice recording from the channel
local voice_recording = channel.record()
-- Read the data out as a base64 encoded string
local res, err = http.post("http://example.com/voice_messages", {data={name='b64', age=voice_recording.base64()}, headers={["Content-Type"]='application/json'}})
-- You can the raw audio data (in .wav format by default)
local res, err = http.post("http://example.com/voice_messages", {data=voice_recording})
-- You can POST it over HTTP as a file
local res, err = http.post("http://example.com/voice_messages", {files={["audio.wav"]=voice_recording}})
-- You can send an mp3 version. Be warned, this takes more time to convert.
local res, err = http.post("http://example.com/voice_messages", {files={["audio.mp3"]=voice_recording.mp3}})

put(url, options)

HTTP PUT request Make a PUT request to the provided URL with the provided params. The URL should include the protocol (e.g. http, https)

Parameters
Name Type Default Summary

url

string

String of url to make request to

options

table

Parameter: options
Name Type Default Summary

basic_auth

table

nil

Table containing {<username>, <password>} for HTTP Basic Auth

data

table

{}

Table of key/value pairs to be send as data with the request. It can also be raw data like a string or a RecordingResult

files

table

{}

Table of filename/filehandle pairs to be sent as file encoded objects with the request.

headers

table

{}

Table of key/value pairs to be sent as request headers.

timeout

float

30

Request timeout. This is not a time limit on the entire reponse download; this only applies if the remote server does not issue any response at all for the specified number of seconds.

Returns
Type Summary

HttpResponse or nil

Table of information about the response (see link), or nil if an error occurred

nil or string

nil if successful, otherwise a description of the error

Usage
local http = require("summit.http")
local asset = require("summit.asset")
local put_file = asset("put_file.txt")
local auth = {'testuser@example.com', 'password123'}
local res, err = http.put('http://example.com/api', {data={name='Tom', age=25}, headers={["Example-Header"]='example/header'}, files={put_file=put_file}, basic_auth=auth})
print(res.url) -- 'http://example.com/api'
print(res.headers) -- e.g. {'content-length': '3', ...}
print(res.content) -- e.g. 'ok'
print(res.statusCode) -- e.g. 200
print(res.reason) -- e.g. 'OK'

urlencode(data)

URL encodes the provided data. This function takes a table of data an converts it to URL-encoded parameters. You should not pass any kind of nested object to this (e.g. {a={b="c"}}) as it will not be encoded properly.

Parameters
Name Type Default Summary

data

table

Data to URL encode

Returns
Type Summary

string

URL encoded data

Usage
local http = require "summit.http"
local data = {first_name = "John", last_name = "Smith"}
local encoded = http.urlencode(data)
print(data)  -- prints `first_name=John&last_name=Smith`