Einführung in die Ninox API

aktualisiert vor 11 Tagen

Ninox API verstehen und Umgebung einrichten

Ninox ist von ninoxdb.de zu ninox.com umgezogen. Die aktuelle Schnittstelle ist api.ninox.com/v1. Wir empfehlen, neue Integrationen auf der neuen Schnittstelle aufzubauen.

Die alte Schnittstelle api.ninoxdb.de/v1 funktioniert weiterhin, sodass Sie alte Integrationen, die mit Zapier, Make oder anderen benutzerdefinierten Lösungen erstellt wurden, nicht migrieren müssen.

Voraussetzungen für die Nutzung der Ninox API

Um die Ninox API nutzen zu können, benötigen Sie Folgendes:

Ninox-Lizenz
Ninox Personal Access Token
Ninox REST API
Abhängig von den Details Ihrer Serverumgebung:
- Public Cloud, Private Cloud oder Private Cloud On-Premises
- Zapier, Make oder eine ähnliche Lösung

Verwenden Sie Postman, um API-Anfragen zu senden. Alternativ können Sie Endpunkte in Ihrer Shell/Ihrem Terminal mit dem Befehl cURL aufrufen. Eine dritte Option ist die Funktion http im Ninox-Formeleditor.

API-Referenz

Die Ninox-API ist eine organisierte RESTful-API. Sie besteht aus vorhersagbaren URLs, formularcodierten Anforderungen, JSON-codierten Antworten und allgemeinen HTTP-Antwortcodes. Die API verwendet auch Standardauthentifizierung und -verben.

Authentifizierung

Die Ninox-API verwendet Bearer Tokens, um Anforderungen zu authentifizieren. Sie können Ihre Personal Access Tokens in Ihren Admin-Einstellungen in der Ninox-Web-App anzeigen und verwalten.

Um Ihre API-Anforderungen zu authentifizieren, fügen Sie den accessToken in den HTTP-Authorization-Header ein. Inhalte in geschweiften Klammern { } kennzeichnen einen Platzhalter. Sowohl die geschweiften Klammern als auch der Inhalt darin müssen ersetzt werden, damit die Authentifizierung funktioniert.

-H "Authorization": "Bearer {accessToken}"

Ninox empfiehlt, API-Anforderungen über HTTPS zu stellen. In der Public und Private Cloud werden HTTP-Anforderungen zu HTTPS umgeleitet. Wenn Sie versuchen, API-Anforderungen über einfaches HTTP zu stellen und der Umleitung nicht folgen, schlagen diese fehl. Auch wenn Sie einen Benutzernamen und ein Passwort haben, schlagen API-Anforderungen ohne Authentifizierung ebenfalls fehl.

Inhaltstyp

Ninox erwartet, dass Dienste ihre Antworten in JSON bereitstellen. Um eine Antwort als gültiges JSON-Objekt bereitzustellen, müssen die Dienste application/json im HTTP-Content-Type-Representationsheader bereitstellen.

-H "Content-Type": "application/json"

Einen Personal Access Token erhalten

Der Personal Access Token, oder API-Schlüssel, ist in jeder HTTP-Anfrage enthalten, die an die Ninox-API gestellt wird.

Wenn Sie der Eigentümer eines Arbeitsbereichs sind, befolgen Sie die folgenden Schritte, um den API-Schlüssel zu erhalten:

Besuchen Sie ninox.com.
Klicken Sie auf den Button Ninox starten, um die Web-App zu öffnen.
- Wenn Sie den Button Ninox starten nicht sehen, melden Sie sich zuerst mit Ihren Ninox-Anmeldedaten an.
Klicken Sie in der oberen rechten Ecke auf das Zahnradsymbol Aktionen.
Wählen Sie im Dropdown-Menü Integrationen aus.
Klicken Sie im Popup-Fenster auf den Button Generieren.
Kopieren Sie den API-Schlüssel in Ihre Zwischenablage.

Um einen Personal Access Token zu löschen oder zu widerrufen, klicken Sie auf das Kreuzsymbol Token löschen, das rechts neben dem generierten API-Schlüssel angezeigt wird.

Ihre Ninox-API-Schlüssel gewähren Lese- und Schreibzugriff auf alle Ihre Datenbanken, also bewahren Sie Ihre Token sicher auf. Geben Sie Ihre geheimen API-Schlüssel nicht in öffentlich zugänglichen Bereichen wie GitHub, clientseitigem Code usw. weiter.

Fehler

Ninox verwendet herkömmliche HTTP-Antwortcodes, um anzugeben, ob eine API-Anfrage erfolgreich war oder nicht. Codes im Bereich 2xx zeigen Erfolg an, Codes im Bereich 4xx zeigen einen Clientfehler an und Codes im Bereich 5xx zeigen einen Serverfehler an.

HTTP-Antwortstatuscodes

Erfolgreiche Antworten

Statuscode	Definition
200 OK	Die Anfrage war erfolgreich. Die Bedeutung des Erfolgs hängt von der HTTP-Methode ab: GET: Die Ressource wurde abgerufen und wird im Nachrichtenkörper übertragen. HEAD: Die Repräsentations-Header sind in der Antwort enthalten, jedoch ohne Nachrichtenkörper. PUT oder POST: Die Ressource, die das Ergebnis der Aktion beschreibt, wird im Nachrichtenkörper übertragen. TRACE: Der Nachrichtenkörper enthält die Anfrage, wie sie vom Server empfangen wurde.
201 Created	Die Anfrage war erfolgreich und eine neue Ressource wurde erstellt. Dies ist typischerweise die Antwort auf POST-Anfragen oder einige PUT-Anfragen.
202 Accepted	Die Anfrage wurde empfangen, aber noch nicht bearbeitet. Es gibt keine Möglichkeit in HTTP, später eine asynchrone Antwort über das Ergebnis der Anfrage zu senden. Dies ist für Fälle gedacht, in denen ein anderer Prozess oder Server die Anfrage bearbeitet oder für Batch-Verarbeitung.
204 No Content	Es gibt keinen Inhalt für diese Anfrage zu senden, aber die Header könnten nützlich sein. Der User-Agent kann seine zwischengespeicherten Header für diese Ressource mit den neuen aktualisieren.

Kundenfehler-Antworten

Statuscode	Definition
400 Bad Request	Der Server konnte die Anfrage aufgrund fehlerhafter Syntax nicht verstehen.
401 Unauthorized	Zwar gibt der HTTP-Standard "unauthorized" an, semantisch bedeutet diese Antwort jedoch "unauthenticated". Das heißt, der Client muss sich authentifizieren, um die angeforderte Antwort zu erhalten.
403 Forbidden	Der Client hat keine Zugriffsrechte auf den Inhalt; das heißt, er ist nicht autorisiert, sodass der Server die angeforderte Ressource verweigert. Im Gegensatz zu 401 ist die Identität des Clients dem Server bekannt.
404 Not Found	Der Server kann die angeforderte Ressource nicht finden. Im Browser bedeutet dies, dass die URL nicht erkannt wird. In einer API kann dies auch bedeuten, dass der Endpunkt gültig ist, aber die Ressource selbst nicht existiert. Server können diese Antwort auch anstelle von 403 senden, um die Existenz einer Ressource vor einem unautorisierten Client zu verbergen. Dieser Antwortcode ist wahrscheinlich der bekannteste aufgrund seines häufigen Auftretens im Web.
422 Unprocessable Entity (WebDAV)	Die Anfrage war gut formatiert, konnte jedoch aufgrund semantischer Fehler nicht ausgeführt werden.

Serverfehler-Antworten

Statuscode	Definition
500 Internal Server Error	Der Server ist auf eine Situation gestoßen, mit der er nicht umgehen kann.
501 Not Implemented	Die Anfragemethode wird vom Server nicht unterstützt und kann nicht bearbeitet werden. Die einzigen Methoden, die Server unterstützen müssen (und daher diesen Code nicht zurückgeben dürfen), sind GET und HEAD.
502 Bad Gateway	Diese Fehlerantwort bedeutet, dass der Server als Gateway gearbeitet hat und eine ungültige Antwort erhalten hat, um die Anfrage zu bearbeiten.

Hier ist der ins Deutsche übersetzte Text unter Beibehaltung des HTML-Codes und der Tabellen: ```html