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.

Syntax

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

Parameters

method: GET, POST, PUT, DELETE

url: a valid HTTP/HTTP URL

headers: a JSON object specifying the HTTP header

body: a string or an arbitrary JSON object

Return value

A JSON object containing either an error or a result property

Examples

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:

HTTP	Ninox script
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"

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" } ] }

JSON syntax	Description
{ }	an empty object
[ ]	an empty array
12.56	a number
"Lisa"	a string
{ name: "Lisa" }	an object containing a string
{ name: "Lisa", age: 28 }	an object containing a string and a number
{ name: "Lisa", age: 28, address: { street: "A Street" } }	an object containing two strings and a number
{ name: "Lisa", children: [ { name: "Charlie" }, { name: "Sarah" } ] }	an object containing an array that contains two strings

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

{ 'Lisa''s name' : "Lisa" }

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