JSON-RPC

Überblick

JSON-RPC ist ein zustandsloses, leichtgewichtiges Remote Procedure Call (RPC) Protokoll. Diese Spezifikation definiert in erster Linie verschiedene Datenstrukturen und die Regeln für deren Verarbeitung. Es ist transportunabhängig, d.h. die Konzepte können innerhalb desselben Prozesses, über Sockets, über http oder in vielen verschiedenen Umgebungen für die Nachrichtenübermittlung verwendet werden. Es verwendet JSON (RFC 4627) als Datenformat.

Es wurde entwickelt, um einfach zu sein!

Konventionen

Die Schlüsselwörter "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" und "OPTIONAL" in diesem Dokument sind wie in RFC 2119 beschrieben zu interpretieren.

Da JSON-RPC JSON verwendet, hat es das gleiche Typsystem (siehe http://www.json.org oder RFC 4627). JSON kann vier primitive Typen (Strings, Numbers, Booleans und Null) und zwei strukturierte Typen (Objects und Arrays) darstellen. Der Begriff "Primitiv" in dieser Spezifikation bezieht sich auf jeden dieser vier primitiven JSON-Typen. Der Begriff "Strukturiert" bezieht sich auf einen der strukturierten JSON-Typen. Wenn in diesem Dokument auf einen JSON-Typ Bezug genommen wird, wird der erste Buchstabe immer groß geschrieben: Objekt, Array, String, Zahl, Boolean, Null. True und False werden ebenfalls großgeschrieben.

Bei allen zwischen dem Client und dem Server ausgetauschten Elementnamen, die für einen Abgleich jeglicher Art in Betracht gezogen werden, sollte die Groß- und Kleinschreibung beachtet werden. Die Begriffe Funktion, Methode und Prozedur können als austauschbar angesehen werden.

Der Client ist definiert als der Ursprung von Request-Objekten und der Handler von Response-Objekten.
Der Server wird als Ursprung von Response-Objekten und als Handler von Request-Objekten definiert.

Eine Implementierung dieser Spezifikation könnte leicht beide Rollen ausfüllen, sogar gleichzeitig, für andere verschiedene Clients oder denselben Client. Diese Komplexität wird in dieser Spezifikation nicht berücksichtigt.

Kompatibilität

JSON-RPC 2.0 Request-Objekte und Response-Objekte funktionieren möglicherweise nicht mit bestehenden JSON-RPC 1.0 Clients oder Servern. Es ist jedoch einfach, zwischen den beiden Versionen zu unterscheiden, da 2.0 immer ein Mitglied namens "jsonrpc" mit dem String-Wert "2.0" hat, während 1.0 dies nicht tut. Die meisten 2.0-Implementierungen sollten versuchen, mit 1.0-Objekten umzugehen, wenn auch nicht mit den Peer-to-Peer- und Class-Hinting-Aspekten von 1.0.

Objekt anfordern

Ein rpc-Aufruf wird durch das Senden eines Request-Objekts an einen Server dargestellt. Das Request-Objekt hat die folgenden Elemente:

jsonrpc - Ein String, der die Version des JSON-RPC-Protokolls angibt. MUSS genau "2.0" sein.

method - Ein String, der den Namen der aufzurufenden Methode enthält. Methodennamen, die mit dem Wort rpc, gefolgt von einem Punkt (U+002E oder ASCII 46) beginnen, sind für rpc-interne Methoden und Erweiterungen reserviert und dürfen NICHT für etwas anderes verwendet werden.

params - Ein strukturierter Wert, der die Parameterwerte enthält, die während des Aufrufs der Methode verwendet werden sollen. Dieses Element KANN weggelassen werden.

id -Ein vom Client festgelegter Identifikator, der einen String, eine Zahl oder den Wert NULL enthalten MUSS, wenn er enthalten ist. Wenn er nicht enthalten ist, wird angenommen, dass es sich um eine Benachrichtigung handelt. Der Wert SOLLTE normalerweise nicht Null sein [1] und Zahlen SOLLTEN KEINE Nachkommastellen enthalten [2].

Der Server MUSS mit demselben Wert im Response-Objekt antworten, wenn er enthalten ist. Dieses Element wird verwendet, um den Kontext zwischen den beiden Objekten zu korrelieren.

[1] Von der Verwendung von Null als Wert für das id-Element in einem Request-Objekt wird abgeraten, da diese Spezifikation den Wert Null für Responses mit einer unbekannten id verwendet. Da JSON-RPC 1.0 den Wert Null für Notifications verwendet, könnte dies zu Verwirrung bei der Handhabung führen.

[2] Bruchteile können problematisch sein, da viele Dezimalbrüche nicht exakt als Binärbrüche dargestellt werden können.

Benachrichtigung

Eine Benachrichtigung ist ein Request-Objekt ohne ein "id"-Mitglied. Ein Request-Objekt, das eine Notification ist, bedeutet, dass der Client kein Interesse an dem entsprechenden Response-Objekt hat und daher kein Response-Objekt an den Client zurückgegeben werden muss. Der Server MUSS NICHT auf eine Benachrichtigung antworten, auch nicht auf solche, die in einer Batch-Anfrage enthalten sind.

Benachrichtigungen sind per Definition nicht bestätigungsfähig, da sie kein Response-Objekt haben, das zurückgegeben werden muss. Daher würde der Client keine Fehler bemerken (wie z.B. "Ungültige Parameter", "Interner Fehler").

Parameter-Strukturen

Falls vorhanden, MÜSSEN die Parameter für den rpc-Aufruf als strukturierter Wert angegeben werden. Entweder nach Position durch ein Array oder nach Name durch ein Objekt.

by-position: params MUSS ein Array sein, das die Werte in der vom Server erwarteten Reihenfolge enthält.
by-name: params MUSS ein Objekt sein, dessen Elementname mit den vom Server erwarteten Parameternamen übereinstimmt. Das Fehlen der erwarteten Namen KANN zu einer Fehlermeldung führen. Die Namen MÜSSEN exakt mit den erwarteten Parametern der Methode übereinstimmen, einschließlich Groß- und Kleinschreibung.

Antwortobjekt

Wenn ein rpc-Aufruf erfolgt, MUSS der Server mit einer Antwort antworten, außer im Falle von Benachrichtigungen. Die Antwort wird als ein einzelnes JSON-Objekt mit den folgenden Elementen ausgedrückt:

jsonrpc - Ein String, der die Version des JSON-RPC-Protokolls angibt. MUSS genau "2.0" sein.

result - Dieses Element ist bei Erfolg ERFORDERLICH.
Dieses Element MUSS NICHT vorhanden sein, wenn beim Aufrufen der Methode ein Fehler aufgetreten ist.
Der Wert dieses Elements wird durch die Methode bestimmt, die auf dem Server aufgerufen wurde.

error - Dieses Element ist bei einem Fehler ERFORDERLICH.
Dieses Element MUSS NICHT vorhanden sein, wenn während des Aufrufs kein Fehler aufgetreten ist.
Der Wert für dieses Element MUSS ein Objekt sein, wie in Abschnitt 5.1 definiert.

id - Dieses Element ist ERFORDERLICH.
Es MUSS mit dem Wert des Elements id im Request Object übereinstimmen.
Wenn bei der Erkennung der id im Request-Objekt ein Fehler auftrat (z.B. Parse-Fehler/ungültige Anfrage), MUSS sie Null sein.

Entweder das Ergebnis- oder das Fehler-Element MUSS enthalten sein, aber beide Elemente MÜSSEN NICHT enthalten sein.

Fehlerobjekt

Wenn ein rpc-Aufruf auf einen Fehler stößt, MUSS das Response Object das Error Element mit einem Wert enthalten, der ein Object mit den folgenden Elementen ist:

code - Eine Zahl, die den aufgetretenen Fehlertyp angibt.
Dies MUSS eine ganze Zahl sein.

message - Ein String mit einer kurzen Beschreibung des Fehlers.
Die Meldung SOLLTE auf einen einzigen prägnanten Satz beschränkt sein.

data - Ein primitiver oder strukturierter Wert, der zusätzliche Informationen über den Fehler enthält.
Dies kann weggelassen werden.
Der Wert dieses Elements wird vom Server definiert (z.B. detaillierte Fehlerinformationen, verschachtelte Fehler usw.).

Die Fehlercodes von und einschließlich -32768 bis -32000 sind für vordefinierte Fehler reserviert. Jeder Code innerhalb dieses Bereichs, der nicht explizit unten definiert ist, ist für die zukünftige Verwendung reserviert. Die Fehlercodes sind nahezu identisch mit denen, die für XML-RPC unter der folgenden URL vorgeschlagen werden: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

code	Meldung	Bedeutung
-32700	Parse-Fehler	Ungültiges JSON wurde vom Server empfangen. Beim Parsen des JSON-Textes ist auf dem Server ein Fehler aufgetreten.
-32600	Ungültige Anfrage	Das gesendete JSON ist kein gültiges Request-Objekt.
-32601	Methode nicht gefunden	Die Methode existiert nicht / ist nicht verfügbar.
-32602	Ungültige Parameter	Ungültige(r) Methodenparameter.
-32603	Interner Fehler	Interner JSON-RPC-Fehler.
-32099 to -32000	Server-Fehler	Reserviert für implementierungsspezifische Server-Fehler.

Der restliche Platz ist für anwendungsspezifische Fehler verfügbar.

Batch

Um mehrere Anfrageobjekte gleichzeitig zu senden, KANN der Client ein Array mit Anfrageobjekten senden.

Der Server sollte mit einem Array antworten, das die entsprechenden Antwortobjekte enthält, nachdem alle Batch-Anfrageobjekte verarbeitet wurden. Für jedes Request-Objekt SOLLTE ein Response-Objekt existieren, außer dass es KEINE Response-Objekte für Benachrichtigungen geben SOLLTE. Der Server KANN einen Batch-RPC-Aufruf als eine Reihe von gleichzeitigen Aufgaben verarbeiten, und zwar in beliebiger Reihenfolge und mit beliebiger Breite der Parallelität.

Die Antwortobjekte, die von einem Batch-Aufruf zurückgegeben werden, KÖNNEN in beliebiger Reihenfolge innerhalb des Arrays zurückgegeben werden. Der Client SOLLTE Kontexte zwischen dem Satz von Request-Objekten und dem resultierenden Satz von Response-Objekten auf der Grundlage des id-Mitglieds innerhalb jedes Objekts abgleichen.

Wenn der Batch-RPC-Aufruf selbst nicht als gültiges JSON oder als Array mit mindestens einem Wert erkannt wird, MUSS die Antwort des Servers ein einzelnes Response-Objekt sein. Wenn im Response-Array, das an den Client gesendet werden soll, keine Response-Objekte enthalten sind, MUSS der Server KEIN leeres Array zurückgeben und sollte überhaupt nichts zurückgeben.

Beispiele

Syntax:

--> Daten an Server gesendet 
<-- Daten an den Client gesendet

rpc call mit Positionsparametern:

--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

--> {"jsonrpc": "2.0", "method": "subtract", "params": [23, 42], "id": 2}

<-- {"jsonrpc": "2.0", "result": -19, "id": 2}

rpc call mit benannten Parametern:

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"subtrahend": 23, "minuend": 42}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}
--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 4}

<-- {"jsonrpc": "2.0", "result": 19, "id": 4}

eine Benachrichtigung:

--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}
--> {"jsonrpc": "2.0", "method": "foobar"}

rpc call einer nicht existierenden Methode:

--> {"jsonrpc": "2.0", "method": "foobar", "id": "1"}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Procedure not found."}, "id": "1"}

rpc call mit ungültigem JSON:

--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error."}, "id": null}

rpc call mit ungültigem Request-Objekt:

--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}

rpc call Batch, JSON ungültig:

--> [ {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},{"jsonrpc": "2.0", "method" ]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error."}, "id": null}

rpc call mit einem leeren Array:

--> [] 
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}

rpc call mit einem ungültigen (aber nicht leeren) Batch:

--> [1]
<-- [ {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null} ]

rpc call mit ungültigem Batch:

--> [1,2,3]
<-- [
 {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}, 
 {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}, 
 {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null} 
]

rpc call Batch:

--> [
 {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
 {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
 {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
 {"foo": "boo"},
 {"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},
 {"jsonrpc": "2.0", "method": "get_data", "id": "9"} 
]
<-- [
 {"jsonrpc": "2.0", "result": 7, "id": "1"},
 {"jsonrpc": "2.0", "result": 19, "id": "2"},
 {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null},
 {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found."}, "id": "5"},
 {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
]

rpc call Batch (alle Benachrichtigungen):

--> [
 {"jsonrpc": "2.0", "method": "notify_sum", "params": [1,2,4]},
 {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
]
<-- //Für alle Benachrichtigungschargen wird nichts zurückgegeben

Erweiterungen

Methodennamen, die mit rpc. beginnen, sind für Systemerweiterungen reserviert und MÜSSEN NICHT für etwas anderes verwendet werden. Jede Systemerweiterung ist in einer zugehörigen Spezifikation definiert. Alle Systemerweiterungen sind OPTIONAL.

Dieses Dokument und Übersetzungen davon dürfen zur Implementierung von JSON-RPC verwendet werden, es darf kopiert und anderen zur Verfügung gestellt werden, und abgeleitete Werke, die es kommentieren oder anderweitig erläutern oder bei seiner Implementierung helfen, dürfen ganz oder teilweise ohne jegliche Einschränkung erstellt, kopiert, veröffentlicht und verteilt werden, vorausgesetzt, der obige Copyright-Hinweis und dieser Absatz werden in alle diese Kopien und abgeleiteten Werke aufgenommen. Dieses Dokument selbst darf jedoch in keiner Weise verändert werden.

Die oben gewährten eingeschränkten Genehmigungen sind unbefristet und können nicht widerrufen werden.

Dieses Dokument und die darin enthaltenen Informationen werden ohne Mängelgewähr zur Verfügung gestellt, und ALLE AUSDRÜCKLICHEN ODER STILLSCHWEIGENDEN GEWÄHRLEISTUNGEN sind AUSGESCHLOSSEN, EINSCHLIESSLICH, ABER NICHT BESCHRÄNKT AUF JEGLICHE GEWÄHRLEISTUNG, DASS DIE VERWENDUNG DIESER INFORMATIONEN KEINE RECHTE VERLETZT ODER JEGLICHE STILLSCHWEIGENDEN GEWÄHRLEISTUNGEN DER HANDELSÜBLICHKEIT ODER DER EIGNUNG FÜR EINEN BESTIMMTEN ZWECK.

JSON-RPC

GFI KerioControl

Überblick

Konventionen

Kompatibilität

Objekt anfordern

Benachrichtigung

Parameter-Strukturen

Antwortobjekt

Fehlerobjekt

Batch

Beispiele

Erweiterungen