APIs erstellen und Datenbank bereitstellen

Wenn Sie eine Schemadatei (.sfn) erstellt haben, ist es jetzt an der Zeit, den Entwurf in einen echten Dienst zu verwandeln. Öffnen Sie die API-Erstellung: Für jede Tabelle stehen APIs zum Anlegen, Abfragen, Bearbeiten und Löschen bereit, und Sie sehen auf einem Bildschirm, wer welche Adresse verwenden darf.

Bei Bedarf können Sie selbst erstellte Abfrage-APIs, APIs für statische Dateien und Echtzeit-Ereignisse mit demselben Dienst verbinden.

Bevor Sie beginnen

• Erforderliche Berechtigung: Benutzer, denen die Berechtigung zur Datenbanknutzung erteilt wurde
• Vorbereitung: Sie müssen zuerst eine Schemadatei (.sfn) erstellen.

API-Erstellung öffnen

Wählen Sie oben im Schemabildschirm die Registerkarte API-Erstellung, um die automatisch erzeugten APIs je Tabelle anzuzeigen.

Automatisch erzeugte APIs

Für jede Tabelle werden standardmäßig die folgenden 5 APIs automatisch erzeugt. Bei Bedarf können Sie auch selbst neue APIs hinzufügen.

Unter Neue API hinzufügen (Custom Endpoint) können Sie eine API hinzufügen, deren Abfrage und Antwortform Sie selbst festlegen. Mit API für statische Dateien hinzufügen können Sie JSON-, XML-, HTML-, Bild- und Binärdateien aus dem Arbeitsbereich passend zum Dateityp bereitstellen.

Statische Dateien oder Ordner als API bereitstellen

1. Wählen Sie API für statische Dateien hinzufügen.
2. Wählen Sie unter Speicherbereich die Option Teambereich oder Persönlicher Bereich.
3. Wählen Sie unter Quelltyp die Option Einzelne Datei oder Ordnerliste · Dateiinhalt und geben Sie anschließend mit Datei auswählen oder Ordner auswählen die Quelle an.
4. Wenn Sie einen Ordner gewählt haben, legen Sie Zulässige Dateiendungen und Unterordner einbeziehen fest. Lassen Sie die Dateiendungen leer, werden alle Formate berücksichtigt.
5. Wählen Sie unter Antwortmodus, ob der Inhalt im Browser angezeigt (Direkt im Browser anzeigen) oder als Datei empfangen werden soll (Herunterladen).
6. Prüfen Sie die Endpunktberechtigungen und stellen Sie dann das Schema bereit.

Eine einzelne Datei liefert ihren Inhalt am festgelegten Endpunkt. Für einen Ordner werden sowohl die Dateiliste als JSON als auch eine Adresse erzeugt, über die der Inhalt anhand der id eines Listeneintrags gelesen wird. Wenn Sie eine Datei umbenennen oder verschieben, ändert sich auch die aus dem Pfad gebildete id; der Client muss daher die aktuelle id oder viewUrl aus der Liste verwenden.

Bei den Funktionsendpunkten legen Sie die Berechtigungen für Funktionen fest, die im gesamten Dienst verwendet werden, etwa Echtzeit-Socket, Datei- und Bild-Upload und KI-Antworten.

Echtzeit-Ereignisse und REST-Bündel importieren

Unter Ereignisdefinitionen des Echtzeit-Sockets können Sie nur Ereignisse schreiben oder ein JSON- oder YAML-Bündel importieren, das die für die Ereignisse benötigten Tabellen und REST-Einstellungen enthält.

1. Wählen Sie KI-Antwort einfügen und fügen Sie das Bündel ein. Ein selbst vorbereitetes Bündel können Sie im selben Format einfügen.
2. Wählen Sie Nach Namen zusammenführen, um vorhandene Ereignisse beizubehalten, oder Alle ersetzen, um alle aktuellen Ereignisse zu ersetzen.
3. Prüfen Sie in der Vorschau, welche Ereignisse hinzugefügt, geändert oder gelöscht werden und wie viele Tabellen, Spalten und REST-Endpunkte hinzugefügt werden.
4. Prüfen Sie Einträge, die mit vorhandenen REST-Einstellungen kollidieren oder deren Format automatisch bereinigt oder ausgeschlossen wurde. Wählen Sie Abweichende REST-Einstellungen überschreiben nur, wenn vorhandene REST-Einstellungen geändert werden müssen.
5. Prüfen Sie das Ergebnis der Serverprüfung, beheben Sie Fehler und wählen Sie Anwenden.

Der Import ändert das gerade bearbeitete Schema. Im tatsächlichen Dienst wird es erst wirksam, wenn Sie Bereitstellen abgeschlossen haben. Auch wenn Sie im Importbildschirm angewendet haben, prüft der Server bei der Bereitstellung die Ereignis- und REST-Regeln erneut; wird die Prüfung nicht bestanden, erfolgt keine Bereitstellung.

Mit benutzerdefinierten Endpunkten APIs jenseits von CRUD erstellen

Wenn die 5 automatisch erzeugten APIs (list/view/create/update/delete) nicht ausreichen, können Sie mit Neue API hinzufügen (Custom Endpoint) das Verhalten deutlich feiner definieren.

Art der Operation

Neben den 5 grundlegenden CRUD-Operationen bietet die Auswahlliste Art der Operation auch diese Optionen.

Als Zielumfang wählen Sie zwischen Sammlung (ganze Tabelle oder mehrere Datensätze, meist ein Pfad ohne :id), Einzelner Eintrag (ein bestimmter Datensatz) und Befehl (benutzerdefinierter befehlsartiger Endpunkt, der nicht in CRUD passt).

Berechtigungen: dieselben drei Stufen wie bei der REST-API

Die Berechtigungen benutzerdefinierter Endpunkte werden genauso festgelegt wie bei den automatisch erzeugten APIs. Die Erläuterung steht direkt auf dem Bildschirm, sodass nichts verwechselt werden kann.

Wenn Sie Mitglieder + Zusatzbedingungen wählen, können Sie Bedingungen zu Stufe, Teamzugehörigkeit, Administratorstatus und Eigentümer (owner) kombinieren. Bedingungen wie „nur ab Stufe 2“ oder „nur Mitglieder des Vertriebsteams“ lassen sich so auf benutzerdefinierte Endpunkte genauso anwenden wie auf automatisch erzeugte REST-API-Endpunkte.

SQL selbst schreiben

In der Basisabfrage auf der Registerkarte Verarbeitungsablauf gibt es einen Editor, in dem Sie das SQL schreiben, das dieser Endpunkt ausführt. Bei automatisch erzeugten APIs öffnet sich derselbe Editor, wenn Sie die Basisabfrage auf Selbst geschriebenes SQL umstellen.

Auch in der Spalte Verarbeitung der REST-API-Liste wird mit einem SQL-Abzeichen angezeigt, dass dieser Endpunkt eine selbst geschriebene Abfrage verwendet. Bedingungen, die sich mit automatisch erzeugten APIs nicht ausdrücken lassen — zum Beispiel aggregatbasierte Bedingungen wie „ablehnen, wenn dieses Mitglied heute bereits 3 oder mehr Zeilen angelegt hat“ — können Sie nur mit diesem SQL-Editor umsetzen.

SQL und Parameter prüfen

Während Sie SQL eingeben, prüft der Browser die Syntax sowie die Tabellen und Spalten des aktuellen Schemas. Enthält ein Fehler oder Hinweis eine Zeilen- und Spaltenangabe, wählen Sie ihn aus, um zur entsprechenden Stelle im Editor zu gelangen. Auch im Bereitstellungsbereich können Sie fehlerhaftes SQL öffnen.

Diese Prüfung führt die Abfrage nicht in der Datenbank aus. Rufen Sie nach der Bereitstellung die API auf, um datenbankspezifische Funktionen, Zugriffsrechte und Ergebnisse mit echten Daten zu prüfen.

Die Parameterliste zeigt die im SQL verwendeten Werte im Format :name. Der Server setzt die reservierten Werte :id, :user_id, :nick und :now. Andere Werte stammen bei Leseanfragen aus dem Query-String und bei Schreibanfragen aus dem Anfragetext nach der Eingabeverarbeitung. Fehlende Werte werden als NULL behandelt.

Anfrageverarbeitung mit dem Verarbeitungsablauf ändern

Auch ohne selbst SQL zu schreiben, können Sie auf der Registerkarte Verarbeitungsablauf vorbereitete Funktionen der Reihe nach hinzufügen und so die Verarbeitung der Anfrage ändern. Die Funktionen sind in drei Stufen unterteilt: Eingabeverarbeitung, DB-Verarbeitung und Ausgabeverarbeitung.

Berechtigungen festlegen

Für jede API können Sie die Zugriffsberechtigung einzeln festlegen. Mit Mitgliedern sind hier die Mitgliedskonten des Arbeitsbereichs gemeint. Sie müssen kein eigenes Anmelde- oder Authentifizierungssystem aufbauen: Das bereits im Arbeitsbereich vorhandene System aus Mitgliedern, Stufen und Teams ist direkt mit den API-Berechtigungen verknüpft.

Bereitstellen

Geben Sie die Bereitstellungsinformationen gemäß den folgenden Schritten ein.

1. Datenbankkennung: Geben Sie in lateinischen Buchstaben den logischen Namen der DB ein, der auf dem Bereitstellungsserver verwendet wird.
2. Storage-Engine-Modus: Wählen Sie SQLite3, PostgreSQL, MySQL oder MariaDB. Für eine externe DB geben Sie zusätzlich Host, Port, DB-Name, Benutzer und Passwort ein. MySQL und MariaDB verwenden eine InnoDB-basierte Konfiguration.
3. Prüfen Sie unter Grundeinstellungen und Erweiterte Einstellungen die folgenden Elemente.

Wählen Sie im Bereitstellungsbereich unterhalb der API-Liste Bereitstellen, um die Einstellungen aufzuklappen. Der Bereitstellungsbereich ist ganz unten im Bearbeitungsbildschirm fixiert und bleibt sichtbar, auch wenn Sie durch die API-Liste scrollen. Die erste Auswahl allein stellt noch nichts bereit. Prüfen Sie die Einstellungen und wählen Sie erneut Bereitstellen; dann werden Datenbank und APIs vorbereitet. Wenn Sie einen Bereitstellungspfad des Clients angegeben haben, wird zusätzlich ein Beispielbildschirm erstellt, mit dem Sie die APIs testen können. Wie Sie den Bildschirm anpassen, erfahren Sie unter Frontend-Beispiel ansehen.

Beispiele für API-Aufrufe

Bereitgestellte APIs werden in der folgenden Form aufgerufen. (Beispiel anhand des Tabellennamens user_profile)

GET  /api/web/{dbName}/user_profile/list
GET  /api/web/{dbName}/user_profile/view/{id}
POST /api/web/{dbName}/user_profile/create
PUT  /api/web/{dbName}/user_profile/update/{id}
DELETE /api/web/{dbName}/user_profile/delete/{id}

Beispiel für eine Anfrage zum Anlegen (POST):

POST /api/web/{dbName}/user_profile/create
Content-Type: application/json

{
  "email": "user@example.com",
  "is_active": true
}

Fehlerantworten lesen

Wenn eine Anfrage fehlschlägt, prüfen Sie den HTTP-Status zusammen mit code oder errorCode. Fehlercodes bleiben in allen Sprachen gleich; entscheiden Sie Aktionen wie Anmeldeaufforderung oder Wiederholung daher anhand des Codes und verwenden Sie message für die Anzeige auf dem Bildschirm.

Die Standard-Fehlermeldungen von Webspace unterstützen Koreanisch, Englisch, Japanisch, vereinfachtes Chinesisch und Deutsch. Zuerst wird die Spracheinstellung des angemeldeten Mitglieds verwendet; fehlt sie oder wird die Sprache nicht unterstützt, wird der Accept-Language-Header der Anfrage herangezogen. Passt keines von beiden, erfolgt die Meldung auf Englisch. Vergleichen Sie in externen API-Integrationen niemals den Anzeigetext selbst.

Eine Anfrage, die eine Anmeldung erfordert, gibt zum Beispiel folgende Informationen zurück.

{
  "code": "WEBSPACE_LOGIN_REQUIRED",
  "errorCode": "WEBSPACE_LOGIN_REQUIRED",
  "message": "Anmeldung erforderlich."
}

Dies sind die Kernfelder, die Sie in einer Fehlerantwort prüfen sollten. Das vollständige Antwortformat kann sich zwischen REST-API, statischen Dateien und Verwaltungs-APIs unterscheiden.

• Antworten der Eingabeprüfung verwenden das bisherige Format mit ok: false und einer errors-Liste. Prüfen Sie ok auch bei HTTP 200 und erläutern Sie das Problem anhand von field, code und message jedes Eintrags.
• WebSocket-Fehler finden Sie in data einer Nachricht vom type: "error". Der bisherige key zur Einordnung bleibt erhalten; code und errorCode unterscheiden die Fehlerursache.
• Tatsächliche Dateipfade des Servers, SQL und interne Fehlertexte werden nicht an Benutzer zurückgegeben. Muss der Betreiber bei einem Fehler das Serverprotokoll prüfen, übermitteln Sie Zeitpunkt, Anfragepfad, HTTP-Status und Fehlercode zusammen.

Bereitstellung und Überschreiben

Das Überschreiben eines Schemas mit vorhandenen Daten folgt der Bereitstellungsrichtlinie des Servers. Je nach Organisationsrichtlinie kann es untersagt oder auf Administratoren oder bestimmte Bereitstellungsverantwortliche beschränkt sein. Prüfen Sie vor einer Strukturänderung die betroffenen Spalten und APIs sowie die Sicherungs- und Wiederherstellungsverfahren.

Hinweise

• APIs werden auf Basis der SetFN-Anmeldesitzung authentifiziert. Nicht authentifizierte Anfragen werden abgelehnt. (Ausnahme: APIs, deren Berechtigung auf Alle gesetzt ist.)
• Wenn Sie die Schemastruktur ändern, werden auch die API-Endpunkte aktualisiert. Prüfen Sie daher die Kompatibilität Ihres bestehenden Integrationscodes.
• SQLite3-Daten werden im Webspace-Speicher des jeweiligen Servers gespeichert, Daten externer Engines in der vom Administrator konfigurierten DB.
• Filter, Sortierung und Seitengröße von Listen verwenden Sie innerhalb des vom Server zugelassenen Abfragebereichs.
• Wenn Sie von einer externen Website aus aufrufen, prüfen Sie auch die vom Administrator erlaubten Origins und die CSP-Einstellungen.

Verwandte Dokumente

• Schemadatei (.sfn) erstellen
• Echtzeit-Gomoku-Spiel erstellen
• Frontend-Beispiel ansehen
• Leistung und Skalierung
• Erste Schritte mit der Webspace-Verwaltung