Ninox websiteForum
Search
⌃K
Links
Comment on page

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
Parameters
Return value
http(method, url)
http(method, url, body)
http(method, url, headers, body)
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
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

1
let response := http("GET", "http://mytestservice.com/path");
2
if response.error then
3
alert(text(response.error))
4
else
5
alert(text(response.result))
6
end

A GET request with an authorization header

1
let response := http("GET", "http://mytestservice.com/path",
2
{
3
"Authorization": "Bearer {accessToken}"
4
}, null);
5
if response.error then
6
alert(text(response.error))
7
else
8
alert(text(response.result))
9
end

A POST request with an authorization header

1
let response := http("POST", "http://mytestservice.com/path",
2
{
3
"Authorization": "Bearer {accessToken}",
4
"Content-Type": "application/json"
5
},{
6
hello: "World",
7
'special character property': 1234
8
});
9
if response.error then
10
alert(text(response.error))
11
else
12
alert(text(response.result))
13
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

1
let response := do as server
2
http("GET", "http://mytestservice.com/path")
3
end;
4
if response.error then
5
alert(text(response.error))
6
else
7
alert(text(response.result))
8
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

1
{ name: "Lisa" }
2
{ name: "Lisa", age: 28 }
3
{ name: "Lisa", age: 28, address: { street: "A Street" } }
4
{ 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

1
{ '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

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

1
{ result: 10 * 5 + 6 } —> { result: 56 }
2
{ 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

1
response.result.id
2
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

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

Handling arrays

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

Example

1
first(response.result)
2
last(response.result)
3
item(response.result, 3)
To loop over the items of an array, use the for...in statement.

Example

1
let firstNames := for item in response.result do
2
item.fields.'First Name'
3
end
Previous
Tables, fields, and records
Next - API
Private Cloud APIs
Last modified 2mo ago