Ninox API Ninox Version 2.3.4 Document version 1.0.0 Ninox 2.3.4 API 1.0.0 Page 1 of 15
Table of Contents Introduction 3 Obtain an API Key 3 Zapier 4 Ninox REST API 5 Authentication 5 Content-Type 5 Get Teams 5 Get Databases 6 Get Tables 6 Get Records 7 Get a single Record 8 Update Records 9 Create Records 10 Delete a Record 10 Table Definitions 11 Ninox HTTP Calls 12 The http Function 12 Examples 12 Calling Services in Server Context 13 Constructing URLs 14 Construction JSON Objects 14 Evaluating JSON Objects 15 Ninox 2.3.4 API 1.0.0 Page 2 of 15
Introduction Ninox provides powerful APIs to enable integration of Ninox with other services. Ninox API is currently in closed beta. It's available for Ninox Cloud customers, only. Currently, there are three main ways to use the API. 1. Zapier: With Zapier it's possible to connect Ninox with other popular services on the Internet just by drag & drop. 2. Ninox REST API: Other services can connect to Ninox by calling the Ninox REST API. 3. Ninox REST Calls: Connect from Ninox to other services using built-in functions to call HTTP services. Obtain an API Key In order to use the Ninox API, you'll need an API Key. The API Key is a secret that is included in every HTTP request to the Ninox API. Make sure to handle the key with care - it gives read and write access to all your databases. Note: Do not include the key in client-side code. Attackers will be able to get access to the token, if it is included in any code that is executed at the client/web browser. 1. Ask Ninox support to enable API access: Send an email to support@ninoxdb.de from the email account you use to sign in to Ninox. 2. Go to https://user.ninoxdb.de and sign in with your user email. 3. Click on </> API. 4. Click on Create API Key. 5. Copy the API Key to the clipboard. Ninox 2.3.4 API 1.0.0 Page 3 of 15
Zapier Zapier is a platform that helps to connect popular services on the Internet. Zapier is not provided by Ninox you'll need an account on that platform which may incur additional costs. 1. Sign up on zapier.com 2. Click on Make a Zap 3. Choose App: Search for Ninox, then click on the most recent version of Ninox 4. Choose between one of two triggers: a) Created Record will fire whenever a new record has been created in a specific table b) New or Updated Record will fire on any create or update of a record in a specific table 5. Select Ninox Account: Click on Connect an Account 6. A dialog will pop up and ask for your API Key (see previous chapter). Copy & paste the API Key. 7. Click on Save + Continue 8. Now, select a Team, a Database and a Table. 9. Click on Continue 10. Click on Fetch & Continue > check for "Test Successful" 11. Click on Continue 12. Choose an Action App, e.g. Slack 13. Configure the app according to the app's documentation. Ninox 2.3.4 API 1.0.0 Page 4 of 15
Ninox REST API HTTP REST / JSON is the most common interface technology these days. Ninox provides REST interfaces to read and update data. We recommend that you use a suitable tool to send HTTP requests. Postman is a good start: https://www.getpostman.com. On Linux and macos you can also use the curl command to issue requests from the shell/terminal. Authentication In order to authenticate API requests, you need to provide the API Key as an HTTP Authorization header. The format is: Authorization: Bearer API-Key Content-Type NX assumes that services will provide their response as a valid JSON object. The services need to provide a Content-Type header with the value "application/json". When calling the Ninox API or sending data to other services you need to explicitly set this header in the http function, see below. Content-Type: application/json Get Teams To get data from Ninox, the first step is to find the right team id. Use this request to list all your teams. Request GET https://api.ninoxdb.de/v1/teams Response [{ }] "id": "67mm9vc324bM7x", "name": "Test-Team" Ninox 2.3.4 API 1.0.0 Page 5 of 15
Get Databases The next step is to find the databases. With the following request you get a list of all databases within a team. Request GET https://api.ninoxdb.de/v1/teams/67mm9vc324bm7x/databases Response [{ }] "id": "nk5xt24oixj4", "name": "Invoices" Get Tables Now, you can list all available tables in that database. Request GET https://api.ninoxdb.de/v1/teams/67mm9vc324bm7x/ databases/nk5xt24oixj4/tables Response [{ }] "id": "A", "name": "Customer", "fields": [{ "id": "A", "name": "First Name", "type": "string" },{ "id": "B", "name": "Last Name", "type": "string" }] The body does not only list all available tables but also the table definitions. Each item consists of three properties: id, name and fields. The id is the table's id that you'll need to provide in order to get, update or delete records. The name is the user-friendly table name. Fields is an array of objects, each describing a column in the table. Each field is defined by an id, a user-friendly name and a type. See chapter "Table Definitions" for more information Ninox 2.3.4 API 1.0.0 Page 6 of 15
Get Records This request returns all records of the specified table. The result set is limited, though - see below. Request GET https://api.ninoxdb.de/v1/teams/67mm9vc324bm7x/ databases/nk5xt24oixj4/tables/a/records Response [{ }] "id": 1, "sequence": 417, "createdat": "2018-06-13T12:16:32", "createdby": "ekl2xsxud7jtn2f2d", "modifiedat": "2018-06-15T16:05:07", "modifiedby": "ekl2xsxud7jtn2f2d", "fields": { "First Name": "Erica", "Last Name": "Young" } The response consists of an array of records. Each record has the following common attributes: Attribute Type Description id integer The record id, starting from 1 sequence integer The database change sequence number, when this record was last updated createdat string The UTC timestamp when the record has been created as YYYY-MM-DDThh:mm:ss createdby string The id of the user who created the record modifiedat string The UTC timestamp when the record has been created as YYYY-MM-DDThh:mm:ss modifiedby string The id of the user who updated the record fields object An object of all data fields, the field name is used as the key, see chapter "Table Definitions" for the value types. Ninox 2.3.4 API 1.0.0 Page 7 of 15
Query Parameters There are a few query parameters to control which and the amount of records to return: Parameter Type Default Example Description page integer 0 12 Result set page perpage integer 100 250 Records per page order string First Name The field name to order the result desc boolean false true Order descending new boolean false true Show newest records first (cannot be combined with order) updated boolean false true Show latest updates first (cannot be combined with order) sinceid integer 42 Show only records with a higher ID sincesq integer 1567 Show only records that are created after the specified database change sequence number Example Request GET https://api.ninoxdb.de/v1/teams/67mm9vc324bm7x/ databases/nk5xt24oixj4/tables/a/records?page=2&perpage=5&order=first%20name Get a single Record If you do know the record id of the record you're interested in, use this request. Request GET https://api.ninoxdb.de/v1/teams/67mm9vc324bm7x/ databases/nk5xt24oixj4/tables/a/records/1 Response { } "id": 1, "sequence": 417, "createdat": "2018-06-13T12:16:32", "createdby": "ekl2xsxud7jtn2f2d", "modifiedat": "2018-06-15T16:05:07", "modifiedby": "ekl2xsxud7jtn2f2d", "fields": { "First Name": "Erica", "Last Name": "Young" } Ninox 2.3.4 API 1.0.0 Page 8 of 15
Update Records Multiple records can be updated and/or created with a single request. The request body must contain an array of all records to create or update. To update a record: Specify the record's id and all fields that shall be updated. To create a record: Leave out the id. Request POST https://api.ninoxdb.de/v1/teams/67mm9vc324bm7x/ databases/nk5xt24oixj4/tables/a/records Headers Content-Type: application/json Body [{ },{ }] "id": 1, "fields": { "First Name": "Erica-Maria" } "fields": { "First Name": "Lisa", "Last Name": "Schmidt" } Response [{ },{ }] "id": 1, "sequence": 418, "createdat": "2018-06-13T12:16:32", "createdby": "ekl2xsxud7jtn2f2d", "modifiedat": "2018-06-15T16:05:07", "modifiedby": "ekl2xsxud7jtn2f2d", "fields": { "First Name": "Erica-Maria", "Last Name": "Young" } "id": 48, "sequence": 418, "createdat": "2018-06-15T16:05:07", "createdby": "ekl2xsxud7jtn2f2d", "modifiedat": "2018-06-15T16:05:07", "modifiedby": "ekl2xsxud7jtn2f2d", "fields": { "First Name": "Lisa", "Last Name": "Schmidt" } Ninox 2.3.4 API 1.0.0 Page 9 of 15
Create Records See Update Records, the same request can be used to create records. Delete a Record A single record can be deleted with the following request. At the time, it's not possible to delete multiple records with one request. Request DELETE https://api.ninoxdb.de/v1/teams/67mm9vc324bm7x/ databases/nk5xt24oixj4/tables/a/records/1 Response {} An empty object indicates that the deletion took effect. Ninox 2.3.4 API 1.0.0 Page 10 of 15
Table Definitions Tables are defined by an id, a human-friendly name and an array of fields. Table ids start with "A", "B", "AA", "AB", Each field is defined by an id, a human-friendly name and a type. Field ids start with "A", "B", "AA", "AB", Note: Table and field ids won't change during the life time of a database. Don't make assumption about the format of an id but use this as an opaque identifier since the format may be subject to change in future versions. Field types are defined as follows: Ninox Field Type JSON Value Example text string "Lisa" number number 13.42 date number "2018-01-23" datetime string "2018-01-23T12:30:00" timeinterval string "123:25:16.123" time string "12:30:00" appointment string "2018-01-23T12:30:00-2018-01-23T13:30:00" boolean boolean true, false choice string "Blue" url string "http://ninoxdb.de" email string "support@ninoxdb.de" phone string "+1 123456789" location string "Marienstraße 10, 10117 Berlin, Germany <52.52202224731445,13.38234806060791>" html string "<h1>hello</h1>" Ninox 2.3.4 API 1.0.0 Page 11 of 15
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 son 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 Ninox 2.3.4 API 1.0.0 Page 12 of 15
A GET request including an authorisation header let response := http("get", "http://mytestservice.com/path", null, { Authorization: "Bearer API-Key" }); 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 Ninox 2.3.4 API 1.0.0 Page 13 of 15
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] } Ninox 2.3.4 API 1.0.0 Page 14 of 15
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 Ninox 2.3.4 API 1.0.0 Page 15 of 15