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