Der API-Konstruktor

Jede API von Keplin ist eine GraphQL-Operation der App: eine Query, die Daten liest, oder eine Mutation, die sie schreibt. Die Bildschirme der App selbst, die Berichte, die Workflows und die externen Systeme rufen alle dieselben APIs auf — was Sie hier definieren, ist der einzige Ein- und Ausgangsweg für Daten der Anwendung.

Eine API kann eine von zwei Naturen haben:

Natur	Was sie ist	Wo es vertieft wird
Pipeline	Eine Folge von Schritten (SQL-Query, HTTP-Aufruf, Skript), die der Reihe nach läuft; das Ergebnis des letzten Schritts ist die Antwort.	Diese Seite
Tabelle	Ein einzelner Block, verbunden mit einer Tabelle des Datenmodells, der die Lese- und Schreiboperationen (get/add/update/delete) für Sie erzeugt.	Die GraphQL-API des Modells

Diese Seite behandelt den Konstruktor selbst: die API erstellen, Argumente definieren, die Pipeline aufbauen, ohne Speichern testen und veröffentlichen.

#Wo die APIs leben

Öffnen Sie innerhalb einer App das Panel Code in der Seitenleiste. Der Abschnitt APIs listet die bestehenden APIs auf — Sie können sie mit Neuer Ordner in Ordnern organisieren — und jede öffnet als Tab des Arbeitsbereichs. Die App hat auch eine Übersichtsseite mit der vollständigen Liste, dem Typ und dem Status jeder API, und der Adresse, unter der sie ausgeliefert werden.

#Eine API erstellen

1. Klicken Sie im Panel Code, in der Zeile APIs, auf den Button + (Neue API). Der Button Neue API der Übersichtsseite bringt Sie an denselben Ort: den Arbeitsbereich der App.
2. Geben Sie einen Name. Der Name ist das GraphQL-Feld, das die Clients aufrufen werden, also folgen Sie der Regel: Buchstaben, Zahlen und Unterstrich, nicht mit einer Zahl beginnend — zum Beispiel getOportunidadesPorConta.
3. Klicken Sie auf API erstellen. Die API entsteht als Entwurf, und der Konstruktor öffnet gleich danach — dort entscheiden Sie die Natur (SQL-Blöcke, HTTP, Skript oder Tabelle).

#Der Konstruktor auf einen Blick

Die Kopfzeile des Konstruktors zeigt den Namen, ein Siegel mit dem Typ (query, mutation oder Tabelle) und den Status (veröffentlicht oder Entwurf). Rechts stehen die Befehle, die für die ganze API gelten:

Befehl	Was er tut
Veröffentlicht	Schaltet die Veröffentlichung ein/aus. Eine API im Entwurf ist nur für die sichtbar, die bauen; externe Clients sehen sie nicht.
Öffentlich (ohne Sitzung)	Macht die API ohne Sitzung und ohne API-Schlüssel erreichbar — für öffentliche Bildschirme der App. Siehe Öffentliche APIs.
Speichern	Speichert die API so, wie sie ist. Speichern ist mit gültigem Namen und gültigen Argumenten immer möglich — halbfertige Arbeit wird trotzdem gespeichert.

Darunter teilt sich die Arbeit in drei Tabs:

Tab	Wofür
Aufbau	Identifikation, Argumente und die Pipeline der Schritte.
Test	Die Pipeline im Entwurf ausführen und die API wie ein Client ausprobieren.
Docs	Fertige Beispiele zum Kopieren, um die API von außen aufzurufen.

#Identifikation

Im Abschnitt Identifikation definieren Sie:

• Operation — Query — liest Daten oder Mutation — schreibt Daten. Die Wahl ist semantisch und praktisch: Mutations bitten vor jeder Testausführung um Bestätigung, weil sie wirklich schreiben.
• Name — das GraphQL-Feld. Ist der Name ungültig, warnt der Konstruktor: „Einfaches camelCase: Buchstaben, Zahlen und Unterstrich, nicht mit einer Zahl beginnend."

Bei einer Tabellen-API gibt es keine Wahl der Operation — die Operationen leiten sich aus den CRUD-Aktionen ab, die Sie im Tabellen-Block aktivieren.

#Argumente

Der Abschnitt Argumente deklariert die Parameter, die die Clients an die API übergeben. Jedes Argument hat:

Spalte	Was sie ist
Name	Bezeichner des Arguments (Buchstaben, Zahlen, Unterstrich; beginnt nicht mit einer Zahl).
Typ	Einer von: String, Int, Float, Boolean, ID, JSON, Upload.
Erf.	Ob der Client das Argument senden muss.
Standard	Der Wert, der verwendet wird, wenn der Client nichts sendet.
Testwert	Nur für den Button Ausführen des Tabs Test — betrifft die Clients nicht.

Innerhalb der Pipeline stehen die Argumente als :name in den Schritten SQL und HTTP zur Verfügung, und als input["args"]["name"] im Schritt Skript.

#Dateien als Argument (Typ Upload)

Ein Argument vom Typ Upload empfängt eine Datei. In dem Fall weicht die Spalte Standard der Wahl des Speichers: App-Standard verwendet den Standardspeicher; alternativ wählen Sie einen der in den Einstellungen der App konfigurierten Speicher (Abschnitt Speicher). So müssen eine API, die Rechnungen empfängt, und eine, die Fotos empfängt, die Dateien nicht am selben Ort ablegen.

Was passiert, wenn die API mit einer Datei aufgerufen wird:

1. Die Datei wird im gewählten Speicher abgelegt.
2. In der Pipeline ist das Argument nicht mehr die rohe Datei, sondern eine Referenz mit filename, mimeType, size und einem token — das ist es, was ein Skript-Schritt in input["args"]["nameDesArgs"] erhält.
3. Die App behält den Eintrag der Datei, wie jede andere von den Benutzern hochgeladene Datei.

Zum Testen verwandelt sich die Spalte des Testwerts in einen Dateiwähler — wählen Sie eine von Ihrem Computer und klicken Sie auf Ausführen.

Von außen wird die Datei als multipart-Variable des GraphQL-Requests gesendet (das Standardformat für GraphQL-Uploads); innerhalb der Plattform kümmern sich die Bildschirme für Sie darum.

#Die Pipeline

Der Abschnitt Pipeline ist, wo die API Gestalt annimmt. Die Regeln sind einfach:

• Die Schritte laufen der Reihe nach; das Ergebnis des letzten ist die Antwort der API.
• Jeder Schritt (ab dem zweiten) kann das Ergebnis des vorherigen erhalten — das Siegel „erhält das Ergebnis von Schritt N" erinnert daran.
• In den Schritten SQL und HTTP steht das vorherige Ergebnis in :prev, und es akzeptiert Pfade: :prev.id, :prev.0.id.
• Schritte fügen Sie mit den Buttons SQL-Query, HTTP-Aufruf und Skript hinzu; der Button Tabelle wandelt die API in die Tabellen-Natur um (und lässt sich nicht mit den übrigen Blöcken kombinieren).

Solange es keine Blöcke gibt, schlägt der Abschnitt den Weg vor: Der Standard ist eine Tabelle des Modells; alternativ baut man eine Pipeline mit den im Folgenden beschriebenen Schritten.

#Schritt SQL-Query

1. Wählen Sie die Datenquelle — eine der in der App registrierten Datenbanken. Ohne Datenquellen zeigt der Schritt die Abkürzung, um die erste zu erstellen.
2. Schreiben Sie die Query im Editor. Schreiben Sie :, um Argumente zu vervollständigen; der Editor kennt die Tabellen und Spalten der gewählten Datenquelle und schlägt sie beim Schreiben vor.
3. Wenn die Query ihrer Natur nach eine einzige Zeile zurückgibt (eine Summe, ein Datensatz pro Schlüssel), schalten Sie Nur die erste Zeile zurückgeben ein — die Antwort wird von einer Liste zu einem Objekt.

Die Werte von :argument und :prev gehen immer parametrisiert zur Datenbank — niemals in den Text der Query hineingeklebt. Das schützt Sie mühelos vor SQL-Injektion.

#Schritt HTTP-Aufruf

Um mit externen Diensten zu sprechen:

1. Wählen Sie die Methode (GET, POST, PUT, PATCH oder DELETE) und füllen Sie die URL aus — z. B. https://api.exemplo.pt/clientes/:clienteId.
2. Fügen Sie Header mit Header hinzufügen hinzu — zum Beispiel Authorization mit dem Wert Bearer :token.
3. Bei Methoden mit Rumpf füllen Sie den Body aus; schalten Sie Als JSON senden ein, damit der Rumpf mit dem richtigen Content-Type mitgeht.

:nameDesArgs und :prev werden in URL, Headern und Body ersetzt.

#Schritt Skript

Der Skript-Schritt führt ein Skript der App aus — dieselbe Logik, die Sie von Hand oder per Zeitplan laufen lassen können, jetzt als Teil einer API:

1. Wählen Sie das Skript in der Liste (die Liste zeigt den Namen und die Sprache jedes einzelnen; nur aktive Skripte erscheinen). Ohne Skripte zeigt der Schritt die Abkürzung, um das erste zu erstellen.
2. Entscheiden Sie, ob der Schritt Erhält das Ergebnis des vorherigen Schritts — beim ersten Schritt der Pipeline gilt dieser Schalter nicht.

Der Vertrag mit dem Skript ist klar: Die Argumente der API kommen in input["args"] an, das Ergebnis des vorherigen Schritts in input["prev"], und der von der Funktion main(input) zurückgegebene Wert geht an den nächsten Schritt weiter (oder ist die Antwort, wenn es der letzte Schritt ist).

#Schritte umordnen und entfernen

Jede Schrittkarte hat Pfeile für Nach oben verschieben / Nach unten verschieben und einen Papierkorb für Schritt entfernen. Die Pipeline zu ändern macht das Ergebnis des letzten Tests ungültig — klicken Sie erneut auf Ausführen, um frische Ergebnisse zu sehen.

#Testen ohne zu speichern

Der Tab Test hat zwei Werkzeuge. Das erste, Pipeline testen (Entwurf), führt die Pipeline SO WIE SIE im Konstruktor STEHT aus, ohne zu speichern:

1. Füllen Sie die Testwerte der Argumente aus (im Abschnitt Argumente).
2. Klicken Sie auf Ausführen. Bei einer Mutation bittet der Konstruktor um Bestätigung — „Die Mutation jetzt ausführen?" — weil der Test ernsthaft gegen die Datenquellen läuft und eine Mutation echte Schreibvorgänge macht.
3. Lesen Sie das Ergebnis: das Siegel Erfolg/Fehler mit der Dauer, die vollständige Antwort (sehr große Antworten erscheinen gekürzt), und bei mehr als einem Schritt das Ergebnis pro Schritt — jeder Schritt mit dem Siegel ok/Fehler, damit Sie genau sehen, wo die Pipeline gebrochen ist.
4. Wenn die Schritte Logs geschrieben haben (ein Skript, das etwas ausgibt, zum Beispiel), erscheinen sie im Block Logs.

#Der Return-Typ

Der Return-Typ ist die Form der Antwort im GraphQL-Schema — er sagt den Clients, welche Felder sie auswählen können. Der Konstruktor leitet ihn aus dem echten Ergebnis ab: Nach jeder Ausführung sehen Sie den Block Return-Typ (abgeleitet). Weicht er vom gespeicherten ab, erscheint der Hinweis „Dieser Return-Typ ist noch nicht gespeichert." mit dem Button Return-Typ speichern — und ein bernsteinfarbener Punkt am Button Speichern erinnert an dasselbe.

#Wie ein Client ausprobieren

Das zweite Werkzeug des Tabs Test ist eine interaktive GraphQL-Umgebung, die auf den Endpunkt der App zeigt — Sie schreiben Operationen, haben Vervollständigung des Schemas und sehen die Antworten. Da Sie authentifiziert sind, erscheinen auch die Entwürfe. Der Button In Fenster öffnen öffnet dieselbe Umgebung in einem Tab des Browsers. Die Details stehen im nächsten Kapitel, in Die GraphQL-API des Modells.

#Veröffentlichen

Der Schalter Veröffentlicht steuert, wer die API sieht:

• Entwurf — nur wer baut, sieht sie (in authentifizierten Sitzungen erscheinen die Operationen als Entwurf markiert). Externe Clients und Benutzer der App sehen sie nicht, auch nicht durch Auflisten des Schemas.
• Veröffentlicht — sie kommt ins Schema für alle Clients mit Zugriff.

Um als veröffentlicht zu speichern, muss die API vollständig sein. Der Konstruktor zeigt die Blockaden neben der Kopfzeile — zum Beispiel „Schritt 2: Das SQL ist leer." oder, bei einer Tabellen-API, „Zum Speichern als veröffentlicht wählen Sie die Tabelle und mindestens eine CRUD-Aktion." Diese Hinweise verhindern niemals das Speichern als Entwurf: Sie verhindern nur die Veröffentlichung.

#Die generierte Dokumentation (Tab Docs)

Der Tab Docs beantwortet die Frage „wie rufe ich das von außen auf?". Er wird aus der gespeicherten Version erzeugt — speichern Sie die API zuerst — und zeigt:

• Den Endpunkt (POST /api/graphql/gestao-clientes), mit Kopier-Button.
• Die Notiz zur Authentifizierung: Der Header x-api-key ist für externe Clients Pflicht — die Schlüssel werden unter API-Schlüssel erzeugt. Im Tab Test (interne Sitzung) ist er nicht nötig.
• Einen Eintrag pro Operation der API mit vier fertigen Blöcken zum Kopieren: GraphQL-Query, Variables, curl und JavaScript (fetch). Bei einer Tabellen-API erscheinen alle aktiven Operationen (get, count, add, update, delete).

#Warum nicht…?

• Warum kann ich nicht veröffentlichen? Die Pipeline ist noch nicht vollständig — lesen Sie die Blockaden neben der Kopfzeile: Jeder fehlende Schritt wird mit Nummer und Grund aufgelistet.
• Warum bittet mich das Ausführen um Bestätigung? Die API ist eine Mutation: Der Test macht echte Schreibvorgänge. Vergewissern Sie sich, dass Sie auf Testdaten zeigen.
• Warum sehe ich meine neue API nicht in der GraphQL-Testumgebung? Speichern Sie zuerst — die Umgebung antwortet über die gespeicherte Version. Gespeicherte Entwürfe erscheinen (Sie sind authentifiziert); für externe Clients erst, wenn Sie veröffentlichen.
• Warum kann ich keinen SQL-Schritt zu einer Tabellen-API hinzufügen? Eine Tabellen-API lässt sich nicht mit anderen Blöcken kombinieren — entfernen Sie zuerst den Tabellen-Block (oder die Schritte, in der umgekehrten Richtung).