API calls in Ninox script

Call Ninox API with the http() function via the formula editor

To call other services on the internet, use the formula editor in the Ninox app and Ninox API. Query information or send updates with the http() function from other REST services. The http() function can be used in triggers with POST, however not with GET.

 When called from a button, the http() function executes in the client/web browser context. To prevent this, place do as server {http(…) end}between the function and the button.

http(method, url)
http(method, url, body)
http(method, url, headers, body)

 Content in curly brackets{ }signifies a placeholder. Both the curly brackets and the content within must be replaced for the request to work.

A GET request without an authorization header

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 with an authorization header

let response := http("GET", "http://mytestservice.com/path",
{
    "Authorization": "Bearer {accessToken}"
}, null);
if response.error then
 alert(text(response.error))
else
 alert(text(response.result))
end

A POST request with an authorization header

let response := http("POST", "http://mytestservice.com/path",
{
    "Authorization": "Bearer {accessToken}",
    "Content-Type": "application/json"
},{
 hello: "World",
 'special character property': 1234
});
if response.error then
 alert(text(response.error))
else
 alert(text(response.result))
end

Calling services in server context

You may want to run HTTP queries through the Ninox Cloud server instead of through the client. This is particularly important when calling non-SSL APIs, as the Ninox native applications for Mac, iPhone, and iPad are unable to query insecure endpoints.

 To enforce execution of code on the Ninox Cloud server, embed the http() function in ado 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

When path parameters contain spaces or special characters, they require specific encoding. To handle that encoding, Ninox script includes a number of functions:

JSON syntax

JSON syntax is derived from JavaScript Object Notation syntax:

• Data is in name/value pairs

  • A name/value pair consists of a field name (in double quotes), followed by a colon, followed by a value

• Data is separated by commas

• Curly braces hold objects

• Square brackets hold arrays

• Numbers as whole numbers with dot . as decimal separator

Example

{ 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.

Example

{ name: "Lisa ""the quoted"" Maria" }

 Optionally, escape reserved key words like order,from, andtoin single quotes' 'when using these key words as property names.

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.

Example

{ name: "Lisa ""the quoted"" Maria" }

 Using expressions to construct a JSON object

Property values and members of arrays can also be constructed using arbitrary Ninox expressions.

Example

{ 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. You can handle and evaluate JSON objects with Ninox script.

Accessing object values

You can access object values or properties by using dot . notation.

Example

response.result.id
response.result.fields.'First Name'

 Converting values

Ninox script is a statically-typed functional language, which means a JSON object has no schema specification. As a result, specifying or converting the type of a property is occasionally needed. To convert values, use the functions text, number, date, datetime, time, appointment, url, and phone.

Example

number(response.result.id)
text(response.result.fields.'First Name')
date(response.result.fields.'Birthday')

Handling arrays

Use the functions first, last, and item to extract an item from an array.

Example

first(response.result)
last(response.result)
item(response.result, 3)

To loop over the items of an array, use the for...in statement.

Example

let firstNames := for item in response.result do
    item.fields.'First Name'
end