NFetch

Purpose #

Function to make asynchronous HTTP requests and then invoke a callback function with the result. It is inspired by the Fetch JavaScript function as implemented in most browsers.

The callback is done on the next frame update loop - it is not run in a parallel thread.

In most cases this supersedes HTTPGet function.

Syntax #

function NFetch(url, request, callback);

Parameters

`callback`	Reference to a function that should be called on success/failure of the async NFetch call
`request`	Request object describing how the request should be made
`url`	The URL to be called e.g. https://exampleapi.notch.one/tests/getText

You cannot call NFetch in the global scope. Easiest to initiate from code initiated by either Init or Update.

Request Object #

The Request object has numerous properties to enable configuration of the HTTP request.

Property	Description	Example
method	One of the following: `GET\|POST\|PUT\|DELETE`	`"GET"`
headers	A list of key/value pairs for HTTP Header items.	`{ 'Content-Type': 'application/json' }`
body	Payload when using POST or PUT	`body: JSON.stringify(myPayload)`
redirect	Decide whether redirects should be followed: `"follow"` or `"error"` or `"manual"`.	`"follow"`
saveToPath	If a file path is provided, the payload of the HTTP response will be saved to the path specified.	`"C:\\Temp\\testimage.png"`
referrer	Either the URL of referring site or `"no-referrer"` or `"client"`	`"no-referrer"`

method is a mandatory property in the Request object, all others are optional.

Callback functions #

On completion/failure of a NFetch async request, the callback function will be called on the next available render loop. The callback function must accept a single parameter: @response@ which is the Response Object.

function handleMyResponse(response)
{
    if (response.ok && response.status === 200)
    {
        Log(response.text());
    }
}

Response Object #

The Response object is populated by the NFetch handler and provided to the defined callback function (see above).

Property	Description	Example
ok	Did the HTTP request succeed	`true`
headers	A list of key/value pairs returned from the server.	`{ 'Content-Type': 'text/html; charset=utf-8' }`
status	Returned HTTP status code	`200`
saveSuccess	If a save to path was requested, then returns whether the file was succesfully written.	`true`
url	Gets the final response URL	`"http://foo.com/bar"`
curlErrorCode	For debugging : The resulting number from the underlying CURL call.	`0`
curlErrorText	For debugging : The resulting error text from the underlying CURL call.	`"r"`

Usage #

You can copy, paste & test all of the below examples, against our test web API server. (https://exampleapi.notch.one/tests/)

GET Plain Text #

req = { method: 'GET' };
NFetch("https://exampleapi.notch.one/tests/getText", req, testTextResponse);

function testTextResponse(response)
{
    if (response.ok && response.status === 200)
    {
        Log(response.text());
    }
}

Save to File #

req = { method: 'GET', 'saveToPath': "C:\\Temp\\mycsv.csv" };
NFetch("https://exampleapi.notch.one/tests/getCSV", req, testCSVResponse);

function testCSVResponse(response)
{
    if (response.ok && response.status === 200)
    {
        Log('Saved csv to disk');
    }
}

Save PNG to File #

req = { method: 'GET', 'saveToPath': "C:\\Temp\\testimage.png" };
NFetch("https://exampleapi.notch.one/tests/getPNG", req, testPNGResponse);

function testPNGResponse(response)
{
    if (response.ok && response.status === 200)
    {
        Log('Saved png to disk');
    }
}

Get and parse JSON #

req = { method: 'GET' };
NFetch("https://exampleapi.notch.one/tests/getJSON", req, testJSONResponse);

function testJSONResponse(response)
{
    if (response.ok && response.status === 200)
    {
        json = response.json();
        Log(json);
        Log(json['elementExamples']['ex_unicodeStr']);
        Log(json['elementExamples']['ex_string']);
        Log(json['elementExamples']['ex_integer']);
        Log(json['elementExamples']['ex_float']);
    }
}

Make request with headers #

req = { method: 'GET', headers: { 'mySpecialToken': 'Blah', 'customHeader': 'meow' } };
NFetch("https://exampleapi.notch.one/tests/headers", req, testHeaders);

function testHeaders(response)
{
    if (response.ok && response.status === 200)
    {
        Log(response.text());
    }
}

POST JSON data #

payload = {
	"mydata": "is awesome",
	"myNumber": 42
}

req = { method: 'POST', body: JSON.stringify(payload), headers: { 'Content-Type': 'application/json' } };
NFetch("https://exampleapi.notch.one/tests/postJSON", req, testPostJSONResponse);

function testPostJSONResponse(response)
{
    if (response.ok && response.status === 200)
    {
        Log('POST JSON success');
    }
}

POST Form Data #

payload = 'fieldA=Hello%20A&fieldB=Hello%20B';

req = { method: 'POST', body: JSON.stringify(payload), headers: { 'Content-Type': 'application/x-www-form-urlencoded' } };
NFetch("https://exampleapi.notch.one/tests/postJSON", req, testPostFormResponse);

function testPostFormResponse(response)
{
    if (response.ok && response.status === 200)
    {
        Log('POST form success');
    }