Ninox REST API

HTTP REST / JSON is the most popular interface technology today. Ninox provides REST interfaces for reading and updating data.

We recommend that you use a suitable tool for sending HTTP requests. Postman is a good start: getpostman.com . On Linux and Mac OS, you can also use the curl command to send requests from the shell / terminal.

authentication

To authenticate API requests, you must specify the API key as the HTTP authorization header. The format is:

Authorization: Bearer API key

Content-Type

NX assumes that services provide their response as a valid JSON object. The services must provide a Content-Type header with the value "application / json". If you call the Ninox API or send data to other services, you must explicitly set this header in the http function, see below.

Content-Type: application / json

List teams

To get data from Ninox, the first step is finding the right team ID. Use this request to list all your teams.

query

GET https://api.ninoxdb.de/v1/teams

answer

[{ 
    "id": "67mm9vc324bM7x",
    "name": "Test Team"
}]

List databases

The next step is to find the databases. The following request provides a list of all databases within a team.

query

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases

answer

[{ 
    "id": "nk5xt24oixj4",
    "name": "Invoices"
}]

List tables

Now you can list all available tables in this database.

query

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables

answer

[{ 
    "id": "A",
    "name": "Customer",
    "fields": [{
        "id": "A",
        "name": "First Name",
        "type": "string"
    }, {
        "id": "B",
        "name": "Last Name",
        "type": "string"
    }]
}]

The answer not only lists all available tables, but also the table definitions. Each element consists of three properties: id, nameand fields. This idis the ID of the table that you must specify to retrieve, update, or delete records. The nameis the user-friendly table name. fieldsis an array of objects, each describing a column in the table. Each field is defined by one id, one user-friendly nameand one type. Further information can be found in the chapter "Table Definitions".

Query records

This request returns all records of the specified table. However, the result set is limited - see below.

query

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records

answer

[{ 
    "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 answer consists of an array of records. Each record has the following general attributes:

attributes grade description
id integer The Datesatz-ID, start with 1
sequence integer The synchronization sequence number of the last change to this record
createdAt string The UTC timestamp of record creation YYYY-MM-DDThh: mm: ss
createdBy string The user ID of the creator
modifiedAt string The UTC timestamp of the last change YYYY-MM-DDThh: mm: ss
modifiedBy string The user ID of the most recent user
fields object An object with all fields, the field name is used as a key, see chapter "Table definitions".

query parameters

There are some query parameters that control which and which number of records to return:

parameter grade default Example description
page integer 0 12 Results page
perPage integer 100 250 Records per page
order string   first name Field name for sorting
desc boolean false true Descending sorting
new boolean false true Show newest records first (not combinable with order)
updated boolean false true Show last changed records first (not combinable with order)
sinceId integer   42 Show only records with a larger ID
sinceSq integer   1567 Show only records created or modified since this sync sequence number

Sample query

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records?page=2&perPage=5&order=First%20Name

Filter records

This request returns all the records of a particular table that meet the criteria defined as query parameters.

Request

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records?filters= {}

Query Parameters

parameter grade default Example description
filters string N / A   Stringified JSON containing criteria for used for filters

Example:
{"fields": {"Email": "support@ninoxdb.de"}}

{ "A": "support@ninoxdb.de"}

page integer 0 12 Results page
perPage integer 100 250 Records per page
order string   first name Field name for sorting
desc boolean false true Descending sorting
new boolean false true Show newest records first (not combinable with order)
updated boolean false true Show last changed records first (not combinable with order)
sinceId integer   42 Show only records with a larger ID
sinceSq integer   1567 Show only records created or modified since this sync sequence number
ids boolean style in which filters are provided true
false
Formats the records that are returned either as a combination of field ID and value, or as a combination of field name and value.
choice style string ids ids
names
Formats the selection box in a record either as an option ID or as a caption for the selected option.

Important NOTE

The query parameter must be escaped using one of the URI component encoding methods.

An example method used for escaping query parameters in Javascript is -  encodeURIComponent ('{"A": "support@ninoxdb.de"}')

so JSON string containing the following -

{ "A": "support@ninoxdb.de"}

after encoding to -

7B%% 22A% 22% 3A% 22support% 40ninoxdb.de% 22% 7D

Example request

GET https: / https: //api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records?filter=% 7B% 22A% 22% 3A% 22support% 40ninoxdb.de% 22% 7D

Query a single record

Wenn Sie die Datensatz-ID des Datensatzes kennen, der Sie interessiert, verwenden Sie diese Anfrage.

Abfrage

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records/1

Antwort

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

Datensätze Ändern

Mehrere Datensätze können mit einer einzigen Anfrage aktualisiert und / oder erstellt werden. Der Anfragetext muss ein Array aller Datensätze enthalten, die erstellt oder aktualisiert werden sollen.

So aktualisieren Sie einen Datensatz: Geben Sie die ID des Datensatzes und alle Felder an, die aktualisiert werden sollen.

Um einen Datensatz zu erstellen: Lassen Sie die ID weg.

Abfrage

POST https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records

Header

Content-Type: application/json

Body

[{
    "id": 1,
    "fields": {
        "First Name": "Erica-Maria"
    }
},{
    "fields": {
        "First Name": "Lisa",
        "Last Name": "Schmidt"
    }
}]

Antwort

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

Datensätze erstellen

Siehe Datensätze ändern, dieselbe Anfrage kann zum Erstellen von Datensätzen verwendet werden, indem die ID weggelassen wird.

Datensätze löschen

Ein einzelner Datensatz kann mit der folgenden Abfrage gelöscht werden. Zur Zeit ist es nicht möglich, mehrere Datensätze mit einer Anfrage zu löschen.

Abfrage

DELETE https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records/1

Antwort

{}

Ein leeres Objekt zeigt an, dass die Löschung wirksam wurde.

Tabellendefinitionen

Tabellen sind definiert durch eine id,einen benutzerfreundlichen Namen name und ein Array von Feldern fields. Tabellen-IDs starten mit "A", "B", … "AA", "AB", …

Jedes Feld wird durch eine id, einen benutzerfreundlichen Namen name und einen Typ type definiert. Feld-IDs beginnen mit"A", "B", … "AA", "AB", … 

Hinweis: Tabellen- und Feld-IDs ändern sich während der Lebensdauer einer Datenbank nicht. Nehmen Sie keine Annahmen über das Format einer ID vor, sondern verwenden Sie diese als undurchsichtigen Bezeichner, da das Format in zukünftigen Versionen möglicherweise geändert wird.

Feldtypen sind wie folgt definiert:

Ninox Feld-Typ JSON-Typ Beispiel
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>"

Suche im einzelnen Datensatz

Mit der folgenden Anfrage können Sie Dateien abrufen, die mit dem Datensatz assoziiert sind.

Abfrage

GET  https://api.ninoxdb.de/v1/teams/:teamid/databases/:databaseid/tables/:tableid/records/:recordid/files


Antwort

[{
   "name": "image3.jpg",
   "contentType": "image/jpeg",
   "size": 56969,
   "modifiedDate": 1550506659843,
   "modifiedUser": "......",
   "seq": 220
}]

File vom Datensatz herunterladen

Mit der folgenden Anfrage können Sie Dateien herunterladen, die an einen Datensatz angehängt sind.

Abfrage

GET https://api.ninoxdb.de/v1/teams/:teamid/databases/:databaseid/tables/:tableid/records/:recordid/files/:filename

Antwort

Die File

File vom Datensatz hochladen

Mit der folgenden Anfrage können Sie Dateien in Ninox record hochladen

Abfrage

POST  https://api.ninoxdb.de/v1/teams/:teamid/databases/:databaseid/tables/:tableid/records/:recordid/files

Content-Type

Content-Type: multipart/form-data

Validierte Dateinamen

Der Name der hochzuladenden Datei sollte nicht die folgenden Sonderzeichen enthalten \,/,*,?,>,<,<,|,".


Antwort

Eine Antwortmeldung mit der Aufschrift "Datei erfolgreich hochgeladen" mit Content-Type = text/html und einem Statuscode von 200 OK.

File aus dem Datensatz löschen

Mit folgender Anfrage können Sie Dateien aus einem Ninox-Datensatz löschen

Abfrage

DELETE  https://api.ninoxdb.test/v1/teams/:teamid/databases/:databaseid/tables/:tableid/records/:recordid/files/:filename
 

Validierte Dateinamen

Bitte geben Sie den Namen der Datei mit der Dateiendung ein.

Antwort

- Erfolgreiches Löschen: Ein Statuscode von 204 Kein Inhalt ohne Meldung.
- Nicht gefunden/bereits gelöscht - Statuscode von 404 Nicht gefunden zusammen mit der Textnachricht "Datei bereits gelöscht".

Ausführen eines Ninox-Skripts

Mit der folgenden Anfrage können Sie jedes gültige Ninox-Skript ausführen.

Im Folgenden sind die Dinge zu beachten -

  1. Die Ausgabe des Skripts wird als Antwort zurückgestreamt.
  2. Skripte, die Kompilierungsfehler aufweisen, beenden die Anfrage mit einer Nullantwort.

Anfrage

The request can be executed both with the methods GET and POST HTTP.

GET https://api.ninoxdb.de/v1/teams/:teamid/databases/:databaseid/query?query=1+2

Query Parameters

parameter grade description example answer
query string Ninox script that is running.
 1 + 2 

 (select contact). 'Email' 
 3 

 ["support@ninoxdb.de", "webinar@ninoxdb.de"] 

Important NOTE

The query parameter must be escaped with all URI component encoding methods.

An exemplary method for escaping query parameters in Javascript is - encodeURIComponent ('1 + 2').

A parameter that contains -

(select contact). 'Email'

after the URI encoding becomes.

(Select 20Contact%). 'Email'

POST https://api.ninoxdb.de/v1/teams/:teamid/databases/:databaseid/query

Request Body Content-Type description example answer

 { "Query": "1 + 2"} 

 application / json  Ninox script that is running.
 { "Query": "1 + 2"} 

 {"query" :( select contact). 'Email'} 
 3 

 ["support@ninoxdb.de", "webinar@ninoxdb.de"]