web-request

local request = require 'web-request'

The web-request module provides a method to make asynchronous http(s) requests. Due to EG-Overlay’s Lua and render thread setup, synchronous requests are not supported.

All requests are performed on a dedicated thread and results are queued as events back to Lua. This means that a module that queues a request during a Lua event will not receive a response until the following frame/events run.

Important

All requests are logged at the INFO level and include the file and line number where the request was queued. This is intended to give EG-Overlay users full transparency and awareness of what web requests are being made, to where, and which modules are making them.

Module authors that use the web-request module directly should also consider caching results so that multiple requests for the same data are not completed.

Functions

web-request.new(url)

Creates a new web-request.webrequest.

Parameters:

url (string) – The URL to make the request to.

Return type:

web-request.webrequest

Version History

Version	Notes
0.0.1	Added

Classes

class web-request.webrequest

A web request object. A single web request object can be used to make multiple requests to the same URL.

addheader(name, value)

Add a custom header to this request. All subsequent requests made by this webrequest will include the header.

Parameters:

• name (string) – The header name, ie. 'Authorization'

• value (string) – The header value.

Returns:

none

Example

request:addheader('Authorization', 'Bearer (API Key)')

Version History

Version	Notes
0.0.1	Added
0.1.0	Renamed from add_header to addheader

addqueryparameter(name, value)

Add a query parameter that will be appended to the URL when making the request.

Parameters:

• name (string) – The parameter name.

• value (string) – The parameter value.

Returns:

none

Version History

Version	Notes
0.0.1	Added
0.1.0	Renamed from add_query_parameter to addqueryparameter

queue(callback_function)

Queue the request to be performed. A webrequest can be queued multiple times to perform the request multiple times to the same URL.

callback_function is a request_completed function that is called when the request is completed.

Parameters:

callback_function (request_completed) – A function that will be called when the request has been completed.

Returns:

none

Callback Functions

request_completed(code, data, request)

A callback function provided to web-request.webrequest.queue(), called when the request is completed.

Parameters:

• code (integer) – The HTTP response code or 0 if an error occurred before the request could be made.

• data (string) – The response body returned by the request. For responses that resulted in HTTP error codes this will contain the error text returned by the server.

• request (web-request.webrequest) – The web-request.webrequest that made the request.

Version History

Version	Notes
0.0.1	Added

Example

Note

Module authors should use the bundled gw2.api module to make API requests. These examples are provided to show how to use this module.

local wr = require 'web-request'
local JSON = require 'JSON'

local api_url = 'https://api.guildwars2.com/v2/'

local req = wr.new(api_url .. 'account')

req:addheader('Authorization', 'Bearer (apikey)')
req:addheader('X-Schema-Version', 'latest')

local function on_completed(code, data, r)
    if code >= 200 && code < 400 then
        local account_data = JSON.parse_string(data)
        print(string.format("Account age: %f days", account_data.age / 60.0 / 24.0))
    else
        if code > 0 then
            print(string.format("Couldn't complete request, got %d: %s", code, data))
        else
            print("Couldn't complete request.")
        end
    end
end

req:queue(on_completed)