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