Notch Notch Manual 0.9.23
 Light | Dark
NFetch

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

callbackReference to a function that should be called on success/failure of the async NFetch call
requestRequest object describing how the request should be made
urlThe 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');
    }