JSON-RPC

aus Wikipedia, der freien Enzyklopädie
Wechseln zu: Navigation, Suche

JSON-RPC (JavaScript Object Notation Remote Procedure Call) ist ein Protokoll zum Aufruf entfernter Methoden in Computersystemen, ähnlich wie XML-RPC (die Daten werden jedoch in JSON statt in XML gesendet).[1] Bei der Spezifikation wurde darauf geachtet, dass JSON-RPC möglichst keine unnötige Komplexität enthält und über verschiedene Kommunikationsprotokolle genutzt werden kann. Dadurch kann es sehr flexibel eingesetzt werden. Zudem unterstützt das Protokoll asynchrone Kommunikation, da alle Anfragen und Antworten einen ID enthalten, was eine einfache Zuordnung von Antworten zu den entspr. Anfragen ermöglicht.

JSON-RPC 1.0 erlaubt Anfragen in beide Richtungen (Peer-to-Peer), JSON-RPC 2.0 verwendet ein Client-Server-Modell.

Funktionsweise[Bearbeiten]

Anfrage[Bearbeiten]

Ein JSON-RPC-Call besteht aus einem JSON-Objekt, das vom Client an einen Server geschickt wird. Mögliche Anfragetypen sind

  • Request (engl. Anfrage): Der Server soll eine Antwort liefern.
  • Notification (engl. Benachrichtigung): Einwegkommunikation, vom Server wird keine Antwort erwartet.
  • Batch Request (engl. Stapelanfrage): Mehrere Anfragen (Notifications oder Requests) werden zusammengefasst gesendet. (Verfügbar ab Version 2.0)


In der folgenden Tabelle sind die Bestandteile eines Request-Objekts aufgelistet.

Bestandteil Beschreibung Bemerkung
jsonrpc Ein String mit dem Namen der JSON-RPC-Version ("2.0") Ab Version 2.0
method Ein String mit dem Namen der Funktion, die aufgerufen werden soll.
params Ein Array oder Objekt mit den Parametern, die der Funktion übergeben werden sollen. Objekt ab Version 2.0
id Ein eindeutiger Identifikator für die Nachricht. Kann jeden beliebigen Datentyp haben (i. d. R. Integer).

Eine Notification zeichnet sich dadurch aus, dass:

  • JSON-RPC Version 2.0: id fehlt
  • JSON-RPC Version 1.0: id null ist

Antwort[Bearbeiten]

Im Fall eines Requests schickt der Server nach der Ausführung der angeforderten Methode eine Antwort als JSON-Objekt zurück an den Client. Die Bestandteile eines Response-Objektes, sind in der folgenden Tabelle aufgelistet.

Bestandteile Beschreibung Bemerkung
jsonrpc Ein String mit dem Namen der JSON-RPC-Version ("2.0") Ab Version 2.0
result Das Rückgabeobjekt der Funktion, falls kein RPC-Fehler auftrat. Andernfalls:
  • Version 2.0: wird dieses Feld weggelassen.
  • Version 1.0: hat dieses Feld den Wert null.
error Das Fehlerobjekt, falls ein RPC-Fehler auftrat. Andernfalls:
  • Version 2.0: wird dieses Feld weggelassen.
  • Version 1.0: hat dieses Feld den Wert null.
id Enthält den gleichen Wert wie id des Requests, der diese Response verursacht hat.

Erhält der Server eine Notification, führt er die angegebene Methode aus, sendet jedoch keine Antwort. Erhält er einen Batch-Request, führt er die aufgelisteten Methoden aus, und sendet eine Batch-Response (d.h. die Antworten auf alle Requests im Batch-Request in einer Nachricht).

Beispiele[Bearbeiten]

In diesen Beispielen steht --> für eine Nachricht vom Client an der Server, und <-- umgekehrt.

Version 2.0[Bearbeiten]

Ein einfaches Beispiel mit einer Anfrage und einer Antwort

--> { "jsonrpc": "2.0", "method": "gibAus", "params": {"Nachricht": "Hallo JSON-RPC"}, "id": 1}
<-- { "jsonrpc": "2.0", "result": "Hallo JSON-RPC", "id": 1}

Weitere Beispiele finden sich am Ende der JSON-RPC 2.0 Spezifikation.

Version 1.0[Bearbeiten]

Ein einfaches Beispiel mit einer Anfrage und einer Antwort

--> { "method": "gibAus", "params": ["Hallo JSON-RPC"], "id": 1}
<-- { "result": "Hallo JSON-RPC", "error": null, "id": 1}

Dieses Beispiel zeigt einen Teil der Kommunikation in einer Chat-Anwendung. Der Chat-Dienst sendet eine Notification für jede Nachricht, die der Client erhalten soll. Der Client sendet einen Request, um eine Nachricht zu senden und erwartet eine positive Rückmeldung, um zu wissen, dass die Nachricht veröffentlicht wurde.[2]

...
--> {"method": "veröffentlicheNachricht", "params": ["Hallo an alle!"], "id": 99}
<-- {"result": 1, "error": null, "id": 99}
<-- {"method": "empfangeNachricht", "params": ["Benutzer1", "Wir unterhielten uns gerade"], "id": null}
<-- {"method": "empfangeNachricht", "params": ["Benutzer3", "Ich muss jetzt los, tschüss"], "id": null}
--> {"method": "veröffentlicheNachricht", "params": ["Ich habe eine Frage!"], "id": 101}
<-- {"method": "ändereStatus", "params": ["abwesend","Benutzer3"], "id": null}
<-- {"result": 1, "error": null, "id": 101}
...

Versionsgeschichte[Bearbeiten]

Die erste Version vom JSON-RPC stammt von 2005. Die Version 2.0 wurde 2010 verabschiedet.

Version Beschreibung Datum
1.0 Original-Version[3] 2005
Entwurf "1.1 WD" Auf HTTP eingeschränkt, benannte Parameter, spezifische Fehlercodes und introspektive Funktionen hinzugefügt. 07.08.2006
Entwurf "1.1 Alt" Alternativer (vereinfachter) Vorschlag für 1.1 WD. 06.05.2007
Entwurf "1.2" Leicht modifizierte Variante von 1.1 Alt. Eine spätere Version wurde in 2.0 umbenannt. 27.12.2007
2.0 aktuelle Spezifikation[4] 2010

Implementierungen[Bearbeiten]

JSON-RPC wurde in verschiedenen Programmiersprachen implementiert, darunter JavaScript, C++, C, C#, Java, Python und PHP.[5] Da JSON aus Unicode-Zeichen besteht, kann JSON-RPC jedoch auch in anderen Programmiersprachen relativ einfach implementiert werden.[6]

Siehe auch[Bearbeiten]

Einzelnachweise[Bearbeiten]

  1. http://groups.google.com/group/json-rpc/web/json-rpc-2-0
  2. specification - JSON-RPC - Trac
  3. http://json-rpc.org/wiki/specification
  4. http://www.simple-is-better.org/json-rpc/jsonrpc20.html
  5. Liste von Implementationen von JSON-RPC
  6. RFC 4627 application/json