Network

Make external HTTP network requests and retrieve the results.

request

Send a network request to an external host address.

core.network.request(url, params)

Parameters

Name	Description	Type	Required
url	The url endpoint for the network request.	String	Y
params	A table of options for the request. See Params Table Keys below.	Table	Y

Params Table Keys

Name	Description	Type	Required
method	The HTTP method for the request ("GET", "POST", etc.).	String	Y
headers	A table of headers to send with the request.	Table	N
body	A string body to send with a "POST" request.	String	N
ssl_verify	Verify SSL cert matches hostname.	Boolean	N

Returns

On success, returns a table with response keys (see below). Otherwise, nil and an error.

Response Table Keys

Name	Description	Type
body	The response body returned by the request, if any.	String
headers	A table of response headers from the request.	Table
status	The HTTP response status of the request.	Number

Example

local resp, err = core.network.request("https://google.com", {
  method = "POST",
  body = "{\"name\":\"JSON\"}",
  headers = {
    ["Content-Type"] = "application/json"
  }
})

if not resp then
  core.log(err)
end

core.log("body", resp.body)
core.log("status", resp.status)

get

Convenience method for a "GET" request.

core.network.get(url[, headers])

Parameters

Name	Description	Type	Required
url	The url endpoint for the "GET" request.	String	Y
headers	Optional headers to send with the request.	Table	N

Returns

On success, returns a response object as a table (see network.request). Otherwise, nil and an error.

Example

local resp, err = core.network.get("https://google.com")
if not resp then
  core.log(err)
end

core.log(resp.body)

post

Convenience method for a "POST" request.

core.network.post(url, body[, headers])

Parameters

Name	Description	Type	Required
url	The url endpoint for the "POST" request.	String	Y
body	A string body to post to the endpoint.	String	N
headers	Optional headers to send with the request.	Table	N

Returns

On success, returns a response object as a table (see network.request). Otherwise, nil and an error.

Example

local body = "Here is some text I am posting."

local resp, err = core.network.post("https://post.com/submit", body)
if not resp then
  core.log(err)
end

core.log(resp.body)

See also: Form Example

getJson

Specialized method that sends a "GET" request to an endpoint that responds with JSON.

core.network.getJson(url[, headers])

Special Response

This method returns a Lua table with the decoded JSON response, not the JSON string.

Parameters

Name	Description	Type	Required
url	The url endpoint for the network request.	String	Y
headers	Optional headers to send with the request.	Table	N

Returns

On success, returns the decoded JSON result as a table. Otherwise, nil and an error.

Example

local resp, err = core.network.getJson("https://getjson.com")

if not resp then
  core.log(err)
end

core.log(resp.some_key)

postJson

Specialized method that sends a "POST" request to an endpoint that expects JSON.

core.network.postJson(url, tbl[, headers])

Special Response

This method takes a Lua table and JSON-encodes it. Do not pass a raw JSON string.

Parameters

Name	Description	Type	Required
url	The url endpoint for to post the JSON data to.	String	Y
tbl	A Lua table of data to be JSON encoded.	String	Y
headers	Optional headers to send with the request.	Table	N

Returns

On success, returns the result as a string. Otherwise, nil and an error.

Example

local data = {
  name = "Tim",
  age = 34
}

local resp, err = core.network.postJson("https://postjson.com", data)

if not resp then
  core.log(err)
end

core.log(resp.body)

pipeline

Run a sequential set of network requests against a specific host address.

core.network.pipeline(requests, url)

Parameters

Name	Description	Type	Required
requests	A table array of request tables. See Request Table Keys below.	Table	Y
url	The url endpoint for to run the requests against.	String	Y

Request Table Keys

Name	Description	Type	Required
path	The endpoint for the request. This is joined with the url provided.	String	Y
method	The HTTP method for the request. Defaults to "GET"	String	N
headers	A table of headers to send with the request.	Table	N
body	A string body to send with a "POST" request.	String	N
ssl_verify	Verify SSL cert matches hostname.	Boolean	N

Returns

On success, a table array of response tables (see below), or nil, and an error.

Response Table Keys

Name	Description	Type
body	The response body returned by the request, if any.	String
headers	A table of response headers from the request.	Table
status	The HTTP response status of the request.	Number

Example

local reqs = {
  {
    --defaults to "GET"
    path = "/page1.html"
  },
  {
    path = "/page2.html",
    method = "POST",
    body = "{\"name\":\"JSON\"}",
    headers = {
      ["Content-Type"] = "application/json"
    }
  }
}

local responses, err = core.network.pipeline(reqs, "http://somesite.com")

if not responses then
  core.log(err)
end

for r=1, #responses do
  if responses[r].status == 200 then
    core.log(responses[r].body)
  end
end

encode

Encode a table for use as post or query arguments.

core.network.encode(tbl)

Parameters

Name	Description	Type	Required
tbl	A table with key/value pairs.	Table	Y

Form Example

local form = core.network.encode({
  firstname = "Sally",
  lastname = "Jones"
})

local resp, err = core.network.post("http://post.com/submit", form)
...

Query Example

local args = core.network.encode({
  page = 1,
  perpage = 10
})

local url = "http://page.com?"..args

local resp, err = core.network.get(url)
...