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