GraphQL, gRPC, WebSocket & SSE

Nicht jede API ist schlichtes Anfrage-Antwort. Apiboo spricht auch GraphQL, WebSocket, Server-Sent Events und gRPC, jeweils in einem eigenen Request-Tab, den du wie jeden anderen Request in Collections speicherst. Diese Seite behandelt jedes Protokoll, das gemeinsame Nachrichtenprotokoll und den Mock-Server, der deine Requests mit selbst definierten Beispielen beantwortet.

Ein Protokoll wählen

Klick auf + in der Tab-Leiste, oder Rechtsklick auf eine Collection oder einen Ordner und Hinzufügen, dann wähl GraphQL, WebSocket, Server-Sent Events oder gRPC (siehe Request anlegen). Jede Art zeigt das Symbol ihres Protokolls auf dem Tab. Neue Tabs heißen zunächst „New GraphQL query“, „New WebSocket“, „New SSE stream“ oder „New gRPC call“.

GraphQL

Ein GraphQL-Request ist ein HTTP-Request mit dem Body GraphQL. Die Wahl von GraphQL stellt die Methode auf POST und fügt den Header Content-Type: application/json hinzu. Im Tab Body bekommst du drei Bereiche:

Das Schema laden

Der Explorer braucht das Schema des Servers, das Apiboo mit einer Introspection-Query holt. Die Auswahl über den Bereichen legt fest, wann:

• No schema (die Vorgabe): Es wird nichts geholt, bis du auf Refresh schema klickst.
• Auto Fetch: Das Schema wird bei jeder Änderung der URL geholt.

Der Abruf sendet die Header des Requests (mit eingesetzten Variablen). Eine API, die für Introspection ein Token verlangt, funktioniert also, sobald das Token gesetzt ist.

Eine Query bauen

Hak im Schema-Explorer Felder und Argumente an, und Apiboo schreibt die Query für dich. Öffnest du eine gespeicherte Query, werden die passenden Felder wieder angehakt. Du kannst die Query auch direkt tippen.

WebSocket

1. Gib eine ws://- oder wss://-URL ein, zum Beispiel ws://localhost:4180/v1/orders/feed.
2. Klick auf Connect (oder drück Enter in der URL). Der Status daneben wechselt von Connecting… zu Connected.
3. Tipp im Tab Message eine Nachricht. Wähl JSON oder Text für den Editor.
4. Klick auf Send oder drück Strg+Enter.
5. Disconnect schließt die Verbindung. Während des Verbindens heißt der Button Cancel.

Der Tab hat drei Bereiche:

WebSocket-Einstellungen

Binäre Nachrichten erscheinen im Protokoll als Base64. WebSocket-Verbindungen laufen nicht über den Proxy aus Einstellungen → Proxy.

Server-Sent Events

Ein Tab Server-Sent Events hört auf einen Strom von Events.

1. Wähl GET oder POST und gib die URL ein.
2. Füg unter Headers Header hinzu, unter Body einen JSON-Body (nur bei POST) und unter Auth ein Bearer Token, falls der Stream eins braucht.
3. Klick auf Connect. Der Status zeigt Connected und wie lange der Stream schon offen ist.
4. Disconnect beendet ihn.

Apiboo sendet Accept: text/event-stream und Cache-Control: no-cache für dich. Bricht die Verbindung ab, verbindet es sich von selbst neu: nach 3 Sekunden oder nach der Pause, die der Server mit retry: verlangt. Beim erneuten Verbinden sendet es Last-Event-ID, damit der Server dort weitermacht, wo er aufgehört hat.

Jedes Event erscheint im Protokoll mit seinem Event-Namen als Tag. Ein [DONE]-Event erscheint als „[DONE] — the stream ended“.

Streams in einem normalen HTTP-Request

Du brauchst nicht immer einen SSE-Tab. Bekommt ein normaler HTTP-Request eine Antwort vom Typ text/event-stream, streamt die Desktop-App sie: Die Antwort zeigt 200 OK · Streaming, Events landen laufend im Protokoll, und aus Senden wird Stopp. Der Zustand des Streams lautet Streaming, Stream ended, Stopped oder Stream broke.

Post-Response-Skripte laufen bei einer gestreamten Antwort nicht, und es gibt keinen Body zum Speichern.

gRPC

gRPC funktioniert in der Desktop-App. Ein gRPC-Tab hat eine Adresse, eine Methodenauswahl und einen Button Invoke.

1. Gib die Serveradresse ein, zum Beispiel localhost:50051.
2. Lade im Tab Service definition die Service-Definition: Server Reflection fragt den Server, Load .proto liest eine .proto-Datei (ihre Imports werden daneben gesucht). Der Tab zeigt, wie viele Services und Methoden gefunden wurden.
3. Hak TLS an, wenn der Server TLS nutzt.
4. Wähl die Methode unter Select a method. Methoden erscheinen als „Service / Method“, streamende tragen den Zusatz „(stream)“.
5. Schreib die Request-Nachricht als JSON in den Tab Message und füg unter Metadata Metadaten hinzu.
6. Klick auf Invoke.

Der Bereich Response zeigt den gRPC-Status (etwa OK), die Dauer, die Antwort als JSON und die Trailers. Eine Server-Streaming-Methode füllt stattdessen das Protokoll mit einer Zeile pro Nachricht.

Das Nachrichtenprotokoll

WebSocket, SSE, gestreamte HTTP-Antworten und gRPC-Streams teilen sich ein Protokoll.

Klick einen Eintrag an, um ihn vollständig zu sehen. Show as wechselt zwischen Text, JSON, XML und HTML; Apiboo wählt selbst passend vor. Verbindungszeilen halten Verbindungsaufbau, Trennung und Wiederverbindungsversuche fest. In der Desktop-App enthält die Verbindungszeile außerdem die Request- und Response-Header des Handshakes.

Das Protokoll behält die letzten 1.000 Einträge und sagt dir, wenn ältere verworfen wurden.

Verbindungen bleiben offen

Eine WebSocket-Verbindung gehört zu ihrem Tab, nicht zu dem, was du gerade ansiehst. Wechselst du zu einem anderen Tab und zurück, sind Verbindung, Protokoll und deine noch nicht gesendete Nachricht noch da. Ein Punkt auf dem Tab zeigt, dass er verbunden ist.

Eine Verbindung schließt sich, wenn du ihren Tab schließt, alle Tabs schließt oder den Arbeitsbereich wechselst.

Mock-Beispiele

Ein Mock-Beispiel ist eine vorbereitete Antwort für einen HTTP-Request. So kannst du gegen eine API arbeiten, die es noch nicht gibt. Klick in der Tab-Zeile des Requests auf Mock, um sie zu öffnen.

1. Speichere den Request zuerst in einer Collection. Dann zeigt der Dialog seine Mock-URL.
2. Klick auf Beispiel hinzufügen.
3. Gib ihm einen Namen, einen Status (Vorgabe 200), einen Content-Type und den Antwort-Body. Füg bei Bedarf Antwort-Header hinzu.
4. Schalte das Beispiel mit seinem Aktiv-Schalter ein oder aus.

Um zwischen mehreren Beispielen zu wählen, nutzt du Query-Parameter abgleichen und Header abgleichen: Ein Beispiel antwortet nur, wenn der Request diese Werte mitbringt. Von den passenden Beispielen gewinnt das mit den meisten Treffern (ein Query-Wert zählt mehr als ein Header). Passt keines, antwortet das erste aktive Beispiel.

Die Quelle ist entweder Beispiel (der Body, den du getippt hast) oder Schema (Daten, die aus einem Schema erzeugt werden, das du im Bereich Schemas der Seitenleiste des API-Clients entwirfst).

Gespeicherte Postman-Antworten werden beim Import einer Collection zu Mock-Beispielen (siehe Was übernommen wird).

Der lokale Mock-Server

Der Mock-Server beantwortet Requests mit deinen Mock-Beispielen. Er läuft in der Desktop-App, nur auf deinem Rechner.

1. Klick in der Titelleiste auf das Server-Symbol mit dem kleinen Pfeil (bei API-Client und Verlauf).
2. Klick auf Local Mock, um ihn zu starten. Das Symbol wird grün, und sein Tooltip nennt den Port.
3. Kopier die Mock-URL eines Requests aus seinem Mock-Dialog und ruf sie aus deiner App oder aus Apiboo auf.

Mock-URLs sehen so aus: http://127.0.0.1:8780/mock/<collection id>/<path>. Der Server startet auf Port 8780 und probiert die nächsten Ports, wenn dieser belegt ist. Er vergleicht Methode und exakten Pfad; Pfadparameter gibt es nicht, /books/1 und /books/2 sind also zwei Routen. CORS ist erlaubt, und Änderungen an deinen Beispielen wirken sofort, solange er läuft.

Ein erneuter Klick auf Local Mock stoppt ihn.

Cloud Mock im selben Menü stellt deine Mocks unter einer von Apiboo gehosteten URL bereit, sodass sie auch ohne deinen Rechner funktionieren. Dafür brauchst du einen bezahlten Plan und einen Cloud- oder Team-Arbeitsbereich (siehe Konto & Pläne).