Öffentliche APIs

Standardmäßig antwortet der GraphQL-Endpunkt einer App nur dem, der sich ausweist: eine Sitzung (der Bildschirme der App oder dessen, der baut) oder ein API-Schlüssel. Aber es gibt legitime Fälle anonymen Zugriffs — ein Kontaktformular auf der Website, ein öffentlicher Bildschirm zur Statusabfrage, ein offener Katalog. Dafür gibt es die öffentlichen APIs: Operationen, die Sie für Requests ohne Sitzung und ohne Schlüssel zu öffnen wählen.

Der Schalter gehört immer Ihnen, API für API — und, bei den Tabellen-APIs, Operation für Operation. Nichts wird aus Versehen öffentlich.

#Was ein anonymer Request ist

Ein Request an den Endpunkt der App (/api/graphql/gestao-clientes, oder /api/graphql unter der veröffentlichten Adresse) ohne Sitzungs-Cookie und ohne Header x-api-key. Das ist es, was die öffentlichen Bildschirme der App tun — Seiten, die vor dem Login ausgeliefert werden — und jeder externe Client, den Sie ohne Zugangsdaten aufrufen.

#Eine Pipeline-API öffentlich machen

1. Öffnen Sie die API im Konstruktor.
2. Schalten Sie in der Kopfzeile den Schalter Öffentlich (ohne Sitzung) ein — der Hinweis bestätigt: „Ohne Sitzung und ohne API-Schlüssel erreichbar — für öffentliche Bildschirme der App."
3. Speichern. Die API muss auch Veröffentlicht sein — ein Entwurf wird niemals an Anonyme ausgeliefert, öffentlich hin oder her.

#Operationen einer Tabellen-API öffentlich machen

Bei einer Tabellen-API ist der öffentliche Zugriff feiner: pro Aktion. Im Tabellen-Block hat die Zeile Öffentlicher Zugriff (ohne Sitzung) einen Schalter pro Aktion (Select, Insert, Update, Delete):

1. Aktivieren Sie zuerst die Aktion unter Bereitgestellte Aktionen — nur bereitgestellte Aktionen können öffentlich sein; eine Aktion auszuschalten schaltet auch ihren öffentlichen Zugriff aus.
2. Schalten Sie den öffentlichen Schalter nur der Operationen ein, die die öffentlichen Bildschirme brauchen. „Nur das Nötige einschalten" — das ist die Hausregel.
3. Speichern.

Ein öffentliches Formular zur Interessensregistrierung, zum Beispiel, braucht ein öffentliches Insert — und sonst nichts: Die Liste, die Bearbeitung und das Entfernen bleiben hinter der Sitzung.

#Was die Anonymen sehen — und was nicht

Der Endpunkt behandelt anonyme Requests mit einem eigenen, engeren Schema:

• Nur die öffentlichen APIs existieren. Die übrigen erscheinen nicht einmal per Introspektion — nicht einmal die Namen. Ein Anonymer kann nicht auflisten, was die App an Privatem hat.
• Jede Operation validiert den Zugriff. Eine nicht-öffentliche Operation in einem anonymen Request aufzurufen gibt den Fehler „Operation not available without a session" zurück — selbst wenn man den Namen kennt.
• Entwürfe niemals. Nur veröffentlichte APIs.
• Es gibt eine Obergrenze der Requests: 120 Requests pro Minute, pro App und pro Ursprungsadresse. Nach der Obergrenze ist die Antwort 429 mit dem Header retry-after, der sagt, wie lange zu warten ist. Für öffentliche Bildschirme reicht das dicke; einfachen Missbrauch bremst es.

#Ohne Sitzung und ohne Schlüssel aufrufen

Ein anonymer Request ist ein normaler POST, ohne Authentifizierungs-Header:

curl -X POST 'https://o-teu-host/api/graphql/gestao-clientes' \
  -H 'content-type: application/json' \
  -d '{"query":"mutation ($nome: String!, $email: String!) { registarInteresse(nome: $nome, email: $email) }","variables":{"nome":"Ana Silva","email":"ana@exemplo.pt"}}'

Der Tab Docs der API gibt Ihnen das genaue Beispiel — ignorieren Sie dort die Zeile mit dem x-api-key, die nur für Clients mit Schlüssel gilt.

#Gute Praktiken

Praktik	Warum
Öffnen Sie das Minimum an Operationen	Jede öffentliche Operation ist der Welt exponierte Angriffsfläche.
Bevorzugen Sie bei Tabellen Lese-Aktionen — und abgezählte Felder	Der Baum Enthaltene Felder gilt auch für Anonyme: Was nicht enthalten ist, geht nicht hinaus.
Öffentliche Schreibvorgänge mit Pflicht-Argumenten und Validierung in der Pipeline	Ein öffentliches Insert akzeptiert, was man ihm sendet — validieren Sie im Skript-Schritt oder mit Regeln des Modells.
Überwachen Sie im Radar	Die öffentlichen Ausführungen werden mit dem Zugriffsmodus aufgezeichnet; anomale Spitzen sieht man dort.

#Warum nicht…?

• Ich habe den Schalter eingeschaltet und der anonyme Request schlägt weiter fehl. Sehen Sie den Status an: Die API muss Veröffentlicht sein, zusätzlich zu Öffentlich — und bei einer Tabelle muss die richtige Aktion den öffentlichen Schalter eingeschaltet haben.
• Warum gibt der Browser einen Fehler zurück, wenn ich den Endpunkt öffne? Die interaktive Umgebung (GraphiQL) des Endpunkts verlangt eine Sitzung auf der Plattform — sie ist ein Werkzeug derer, die bauen. Die Daten fordert man per POST an, wie im Beispiel oben.
• Warum erhalte ich 429? Sie haben die anonyme Obergrenze der Adresse erreicht. Warten Sie die Zeit des retry-after. Wenn Ihre Integration mehr braucht, verwenden Sie einen API-Schlüssel — die Limits eines Schlüssels sind von der anonymen Obergrenze unabhängig.
• Respektiert eine öffentliche Operation die Berechtigungen der Benutzer der App? Ein Anonymer ist kein Benutzer — es gibt keinen Benutzer-Datenbereich anzuwenden. Exponieren Sie in öffentlichen Operationen nur Daten, die wirklich allen gehören dürfen.