Ninox HTTP Calls
With the NX scripting language it is possible to call other services on the Internet. With the http
function you can either query for information from other REST services or send updates.
The http Function
With this function, it's possible to call another HTTP endpoint.
Syntax
http(method, url)
http(method, url, body)
http(method, url, headers, body)
Parameters
method: "GET", "POST", "PUT", "DELETE"
url: a valid http/https url
headers: a json object specifying the http header
body: a string or an arbitrary json object, see below
Return Value
A json object containing either an error or a result property.
Note 1: The http function must not be used in triggers.
Note 2: When called from a button, the http function will execute in the client/web browser context. This can be prevented by using a do as server http(…) end block.
Examples
A simple GET request
let response := http("GET", "http://mytestservice.com/path");
if response.error then
alert(text(response.error))
else
alert(text(response.result))
end
A GET request including an authorisation header
let response := http("GET", "http://mytestservice.com/path", {
Authorization: "Bearer API-Key"
}, null);
if response.error then
alert(text(response.error))
else
alert(text(response.result))
end
A POST request
let response := http("POST", "http://mytestservice.com/path", {
hello: "World",
'special character property': 1234
}, {
Authorization: "Bearer API-Key",
'Content-Type': "application/json"
});
if response.error then
alert(text(response.error))
else
alert(text(response.result))
end
Calling Services in Server Context
Sometimes, it is desirable to not execute HTTP requests in the context of the client but in the context of the Ninox Cloud server. This is especially required when calling endpoints that are not secured by SSL — since the Ninox native apps for Mac, iPhone and iPad are not able to query such insecure endpoints.
To enforce execution of code on the Ninox Cloud server, you can embed in a do as server block. Example:
let response := do as server
http("GET", "http://mytestservice.com/path")
end;
if response.error then
alert(text(response.error))
else
alert(text(response.result))
end
Constructing URLs
URL query parameters need a special encoding when they contain spaces or special characters. NX script provides a range of functions to handle that encoding:
urlEncode("Test Parameter") —> "Test%20Parameter"
urlDecode("Test%20Parameter") —> "Test Parameter"
url("http://mytestapi.com", { page: 1, perPage: 20, order: "First Name" })
—> "http://mytestapi.com?page=1&perPage=20&order=First%20Name"
Construction JSON Objects
JSON objects are denoted quite similar to the JavaScript syntax. Curled parenthesis { } denote an object. Object properties are in the form name: value, separated by comma. Braces [ ] denote an array. String values are expressed by double quotes "value". Number values as plain numbers with a dot as the decimal separator, like 12.56.
Some examples:
{ } — an empty object
[ ] — an empty array
12.56 — a number
"Lisa" — a string
{ name: "Lisa" }
{ name: "Lisa", age: 28 }
{ name: "Lisa", age: 28, address: { street: "A Street" } }
{ name: "Lisa", children: [ { name: "Charlie" }, { name: "Sarah" } ] }
Escaping object property names:
When a property name contains spaces or special characters or starts with a number, it needs to be quoted in single quotes ' '. To include a single quote within a property name, write two single quotes, e.g.
{ 'Lisa''s name' : "Lisa" }
Note on key words: reserved key words like order, from, to can but do not need to be escaped in single quotes when used as a property name.
Escaping string values:
String values need to be enclosed in double quotes " ". To include a double quote within a string value, write two double quotes:
{ name: "Lisa ""the quoted"" Maria" }
Using expressions to construct a JSON object
Property values and members of arrays can also be constructed using arbitrary NX expressions. Some examples:
{ result: 10 * 5 + 6 } —> { result: 56 }
{ powers: for i in [1, 2, 3] do i*i end } —> { powers: [1, 4, 9] }
Evaluating JSON Objects
Most services will return JSON objects. With NX script it is possible to handle and evaluate JSON objects.
Get a property
The dot notation gives easy access to properties. Examples:
response.result.id
response.result.fields.'First Name'
Converting values
Since NX script is internally a strong static typed functional language, and there's no schema definition for a JSON object, it is sometimes necessary to explicitly specify or convert the type of a property. Use the functions text, number, date, datetime, time, appointment, url, phone to convert values. Some examples:
number(response.result.id)
text(response.result.fields.'First Name')
date(response.result.fields.'Birthday')
Handling arrays
The functions first, last and item can be used to extract an item from an array:
first(response.result)
last(response.result)
item(response.result, 3)
To loop over the items of an array, use a for in loop:
let firstNames := for item in response.result do
item.fields.'First Name'
end