Was ist JSON-RPC? Protokoll, Beispiele, REST-Vergleich

Was ist JSON-RPC?

JSON-RPC ist ein leichtgewichtiges Protokoll für Remote Procedure Calls (RPC), das Requests und Responses als JSON kodiert. Der Client nennt eine Methode samt Parametern, der Server führt sie aus und liefert ein Ergebnis oder einen Fehler. Es ist zustandslos und transportunabhängig: Die JSON-RPC-2.0-Spezifikation (von 2010) beschreibt Nachrichten, nicht deren Übertragungsweg.

Sie begegnen ihm in Ethereum-Nodes, im Language Server Protocol hinter Code-Editoren und im Model Context Protocol für KI-Werkzeuge. Alle drei nutzen JSON-RPC-2.0-Nachrichten.

So läuft ein JSON-RPC-Aufruf ab

Ein Request hat vier Felder: jsonrpc (immer "2.0"), method (der aufzurufende Name), params (optional, ein Array für Positionsargumente oder ein Objekt für benannte Argumente) und id (ein String oder eine Zahl Ihrer Wahl, die in der Antwort zurückkommt).

{"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}

Eine erfolgreiche Antwort enthält dieselbe id und ein result:

{"jsonrpc": "2.0", "result": 19, "id": 1}

Ein fehlgeschlagener Aufruf enthält statt eines Ergebnisses ein error-Objekt mit numerischem code und einer message:

{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": 1}

Über HTTP ist das ein einzelner POST an eine feste URL, wobei der Methodenname im Body steht statt im Pfad. Mit curl können Sie es ausprobieren: Senden Sie das Request-Objekt als Body mit Content-Type: application/json.

Notifications und Batch-Requests

Ein Request ohne id ist eine Notification: Der Server darf nicht antworten, der Client erfährt also nie, ob es geklappt hat.

{"jsonrpc": "2.0", "method": "log", "params": {"level": "info"}}

Mehrere Aufrufe auf einmal senden Sie, indem Sie die Request-Objekte in ein Array legen. Der Server antwortet mit einem Array von Responses, und die Spezifikation erlaubt jede Reihenfolge. Ordnen Sie daher jede Response über die id dem Request zu.

[
  {"jsonrpc": "2.0", "method": "sum", "params": [1, 2, 4], "id": 1},
  {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 2}
]

Standard-Fehlercodes

JSON-RPC, REST und gRPC im Vergleich

Wählen Sie REST, wenn Ihre API Ressourcen abbildet und HTTP-Caching und Statuscodes für Sie arbeiten sollen. Wählen Sie JSON-RPC, wenn das natürliche Modell "führe diese Aktion aus" lautet, etwa beim Senden einer Transaktion oder wenn ein Language Server Vervollständigungen liefern soll.

Häufige Fehler

• HTTP 200 als Erfolg werten. Viele Server antworten mit 200, auch wenn der Body ein error enthält. Prüfen Sie den Body.
• Eine id innerhalb einer Verbindung wiederverwenden. Antworten lassen sich dann nicht zuordnen, vor allem bei Batches nervig.
• Annehmen, dass Batch-Antworten in Reihenfolge kommen. Die Spezifikation verspricht das nicht.
• Einen Aufruf als Notification senden. Fehlt die id, sehen Sie weder Ergebnis noch Fehler.
• null als id verwenden. Die Spezifikation rät davon ab, MCP verbietet es.
• Zugangsdaten in die Nutzlast packen. Authentifizieren Sie stattdessen auf Transportebene, etwa mit einem Bearer Token im Authorization-Header.

JSON-RPC-Endpoints testen und überwachen

Da Fehler meist mit Status 200 zurückkommen, übersieht eine reine Statusprüfung sie. Prüfen Sie stattdessen den Body: error fehlt, result ist vorhanden und id stimmt. Das LoadFocus API-Monitoring unterstützt Assertions auf Statuscode, Body und Antwortzeit, kostenlose Checks laufen alle 5 Minuten.

Beachten Sie bei Lasttests: Ein Batch ist ein HTTP-Request, aber viele Methodenaufrufe, belastet Ihr Backend also anders als dieselben Aufrufe einzeln. Verwenden Sie pro Aufruf eindeutige IDs und testen Sie zuerst die Methoden, die Ihre Datenbank oder einen Blockchain-Node ansprechen. LoadFocus Lasttests führen JMeter- und k6-Skripte aus, die JSON-Bodys senden können, und diese Anleitung zum Lasttest von APIs zeigt die Einrichtung. Was Sie als Ziel angeben, erklärt der Eintrag API-Endpoint.

Häufige Fragen: JSON-RPC

Wird JSON-RPC noch verwendet?

Ja. Ethereum-Clients bieten eine JSON-RPC-Schnittstelle, das Language Server Protocol nutzt es zwischen Editor und Language Server, und das Model Context Protocol baut auf JSON-RPC 2.0 auf. Für öffentliche Web-APIs ist es seltener, dort dominiert REST.

JSON-RPC oder REST: was ist besser?

Keins von beiden pauschal. REST passt zu ressourcenorientierten öffentlichen APIs. JSON-RPC passt zu aktionsorientierten Schnittstellen, bei denen Sie eine Methode aufrufen, und funktioniert auch über andere Transporte als HTTP.

Nutzt JSON-RPC HTTP-Statuscodes?

Die Spezifikation definiert keine. Fehler stehen im Response-Body, und viele Server antworten in beiden Fällen mit 200. Manche Implementierungen bilden Fehler auf HTTP-Codes ab, lesen Sie daher die Dokumentation des Servers.

Wie authentifiziere ich eine JSON-RPC-API?

Das Protokoll hat keine eigene Authentifizierung. Nutzen Sie, was der Transport bietet: einen API-Key oder Bearer Token im Header über HTTP oder einen Mechanismus auf Verbindungsebene bei WebSocket.

Was unterscheidet JSON-RPC 1.0 von 2.0?

Version 2.0 kennzeichnet Nachrichten mit dem Feld jsonrpc und markiert eine Notification durch eine fehlende id (1.0 nutzte eine null-id). Außerdem definiert sie benannte Parameter, Batch-Requests und einen reservierten Bereich für Fehlercodes. Beide Versionen sind womöglich nicht kompatibel, nutzen Sie daher 2.0 für alles Neue.

Kann JSON-RPC Daten vom Server pushen?

Über eine dauerhafte Verbindung wie WebSocket ja: Beide Seiten können Notifications senden. Über reines HTTP startet nur der Client einen Request.