Notch Reference Manual

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.

Syntax

NFetch function

function NFetch(url, request, callBack);

Parameter Description Example
url The URL to be called "https://exampleapi.notch.one/tests/getText"
request Request object describing how the request should be made { method: 'GET', 'saveToPath': "C:\\Temp\\mycsv.csv" }
callBack Reference to a function that should be called on success/failure of the async NFetch call myFunc

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"

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');
    }