KerioControl – JSON-RPC 2.0-Spezifikation

Übersicht

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

Es ist so konzipiert, dass es einfach ist!

Konventionen

Die Schlüsselwörter „MUST“, „MUST NOT“, „REQUIRED“, „SHALL“, „SHALL NOT“, „SHOULD“, „SHOULD NOT“, „RECOMMENDED“, „MAY“ und „OPTIONAL“ in diesem Dokument sind gemäß der Beschreibung in RFC 2119 auszulegen.

Da JSON-RPC JSON verwendet, verfügt es über dasselbe Typsystem (siehe http://www.json.org oder RFC 4627). JSON kann vier primitive Typen (Zeichenketten, Zahlen, Boolesche Werte und Null) sowie zwei strukturierte Typen (Objekte und Arrays) darstellen. Der Begriff „primitiv“ bezieht sich in dieser Spezifikation auf jeden dieser vier primitiven JSON-Typen. Der Begriff „strukturiert“ bezieht sich auf jeden der beiden strukturierten JSON-Typen. Wann immer in diesem Dokument auf einen JSON-Typ Bezug genommen wird, wird der erste Buchstabe immer großgeschrieben: Objekt, Array, Zeichenkette, Zahl, Boolescher Wert, Null. „True“ und „False“ werden ebenfalls großgeschrieben.

Alle zwischen dem Client und dem Server ausgetauschten Mitgliedsnamen, die für einen Abgleich jeglicher Art herangezogen werden, sollten als groß- und kleinschreibungsabhängig betrachtet werden. Die Begriffe „Funktion“, „Methode“ und „Prozedur“ können als austauschbar angesehen werden.

Der Client ist definiert als Ursprung von Request-Objekten und als Verarbeiter von Response-Objekten.
Der Server ist definiert als Ursprung von Response-Objekten und als Verarbeiter von Request-Objekten.

Eine Implementierung dieser Spezifikation könnte problemlos beide Rollen übernehmen, sogar gleichzeitig, und zwar für verschiedene Clients oder denselben Client. Diese Spezifikation befasst sich nicht mit dieser Komplexitätsebene.

Kompatibilität

JSON-RPC 2.0-Anfrageobjekte und Antwortobjekte 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 Element namens „jsonrpc“ mit dem String-Wert „2.0“ enthält, während dies bei 1.0 nicht der Fall ist. Die meisten 2.0-Implementierungen sollten versuchen, 1.0-Objekte zu verarbeiten, auch wenn dies nicht für die Peer-to-Peer- und Class-Hinting-Aspekte von 1.0 gilt.

Anfrageobjekt

Ein RPC-Aufruf erfolgt durch das Senden eines Request-Objekts an einen Server. Das Request-Objekt verfügt über die folgenden Elemente:

jsonrpc – Eine Zeichenkette, die die Version des JSON-RPC-Protokolls angibt. MUSS genau „2.0“ lauten.

Methode – Eine Zeichenkette, die den Namen der aufzurufenden Methode enthält. Methodennamen, die mit dem Wort „rpc“ beginnen, gefolgt von einem Punkt (U+002E oder ASCII 46), sind für rpc-interne Methoden und Erweiterungen reserviert und DÜRFEN NICHT für andere Zwecke verwendet werden.

params – Ein strukturierter Wert, der die Parameterwerte enthält, die beim Aufruf der Methode verwendet werden sollen. Dieses Element KANN weggelassen werden.

id – Eine vom Client festgelegte Kennung, die, sofern angegeben, einen String, eine Zahl oder den Wert NULL enthalten MUSS. Wird sie nicht angegeben, wird davon ausgegangen, dass es sich um eine Benachrichtigung handelt. Der Wert SOLLTE normalerweise nicht NULL sein [1], und Zahlen SOLLTEN KEINE Dezimalstellen enthalten [2].

Der Server MUSS mit demselben Wert im Response-Objekt antworten, sofern dieses enthalten ist. Dieses Element dient dazu, den Kontext zwischen den beiden Objekten zu verknüpfen.

[1] Von der Verwendung von „Null“ als Wert für das „id“-Element in einem „Request“-Objekt wird abgeraten, da in dieser Spezifikation der Wert „Null“ für Antworten mit einer unbekannten ID verwendet wird. Da außerdem JSON-RPC 1.0 den Wert „Null“ für die ID von Benachrichtigungen verwendet, könnte dies zu Verwirrung bei der Verarbeitung 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 das Element „id“. Ein „Request“-Objekt, das eine Benachrichtigung darstellt, bedeutet, dass der Client kein Interesse an dem entsprechenden „Response“-Objekt hat, weshalb dem Client kein „Response“-Objekt zurückgegeben werden muss. Der Server DARF NICHT auf eine Benachrichtigung antworten, auch nicht auf solche, die Teil einer Batch-Anfrage sind.

Benachrichtigungen lassen sich per Definition nicht bestätigen, da sie kein „Response“-Objekt enthalten, das zurückgegeben werden könnte. Daher würde der Client keine Fehler (wie z. B. „Ungültige Parameter“, „Interner Fehler“) bemerken.

Parameterstrukturen

Falls vorhanden, MÜSSEN die Parameter für den RPC-Aufruf als strukturierter Wert angegeben werden. Entweder positionsbezogen über ein Array oder namensbezogen über 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 Elementnamen mit den vom Server erwarteten Parameternamen übereinstimmen. Fehlen erwartete Namen, KANN dies zu einem Fehler führen. Die Namen MÜSSEN exakt – einschließlich Groß- und Kleinschreibung – mit den von der Methode erwarteten Parametern übereinstimmen.

Antwortobjekt

Wenn ein RPC-Aufruf erfolgt, MUSS der Server mit einer Antwort reagieren, außer im Falle von Benachrichtigungen. Die Antwort wird als einzelnes JSON-Objekt mit den folgenden Elementen dargestellt:

jsonrpc – Eine Zeichenkette, die die Version des JSON-RPC-Protokolls angibt. MUSS genau „2.0“ lauten.

Ergebnis – Dieses Element ist bei Erfolg ERFORDERLICH.
Dieses Element DARF NICHT vorhanden sein, wenn beim Aufruf der Methode ein Fehler aufgetreten ist.
Der Wert dieses Elements wird durch die auf dem Server aufgerufene Methode bestimmt.

Fehler – Dieses Element ist im Fehlerfall ERFORDERLICH.
Dieses Element DARF NICHT vorhanden sein, wenn beim Aufruf kein Fehler ausgelöst wurde.
Der Wert dieses Elements MUSS ein Objekt sein, wie in Abschnitt 5.1 definiert.

id – Dieses Element ist ERFORDERLICH.
Es MUSS mit dem Wert des id-Elements im Request-Objekt übereinstimmen.
Sollte bei der Erkennung der id im Request-Objekt ein Fehler aufgetreten sein (z. B. Parsing-Fehler/ungültige Anfrage), MUSS der Wert Null sein.

Entweder das Ergebnis-Element oder das Fehler-Element MUSS enthalten sein, aber es DÜRFEN NICHT beide Elemente enthalten sein.

Fehlerobjekt

Wenn bei einem RPC-Aufruf ein Fehler auftritt, MUSS das Response-Objekt das Element „error“ enthalten, dessen Wert ein Objekt mit den folgenden Elementen ist:

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

message – Ein String, der eine kurze Beschreibung des Fehlers enthält.
Die Meldung SOLLTE auf einen einzigen, prägnanten Satz beschränkt sein.

data – Ein primitiver oder strukturierter Wert, der zusätzliche Informationen zum Fehler enthält.
Dieser Wert kann weggelassen werden.
Der Wert dieses Elements wird vom Server festgelegt (z. B. detaillierte Fehlerinformationen, verschachtelte Fehler usw.).

Die Fehlercodes von -32768 bis einschließlich -32000 sind für vordefinierte Fehler reserviert. Jeder Code innerhalb dieses Bereichs, der im Folgenden nicht ausdrücklich definiert ist, ist für die zukünftige Verwendung reserviert. Die Fehlercodes entsprechen weitgehend den für XML-RPC empfohlenen Codes unter folgender URL: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

Der verbleibende Platz steht für anwendungsspezifische Fehler zur Verfügung.

Stapel

Um mehrere Request-Objekte gleichzeitig zu senden, KANN der Client ein Array senden, das mit Request-Objekten gefüllt ist.

Der Server sollte mit einem Array antworten, das die entsprechenden Response-Objekte enthält, nachdem alle Request-Objekte des Batches verarbeitet wurden. Für jedes Request-Objekt SOLLTE ein Response-Objekt vorhanden sein, mit der Ausnahme, dass es KEINE Response-Objekte für Benachrichtigungen geben SOLLTE. Der Server KANN einen Batch-RPC-Aufruf als eine Reihe von parallelen Aufgaben verarbeiten, wobei er diese in beliebiger Reihenfolge und mit beliebigem Parallelitätsgrad verarbeitet.

Die von einem Batch-Aufruf zurückgegebenen Response-Objekte KÖNNEN in beliebiger Reihenfolge innerhalb des Arrays zurückgegeben werden. Der Client SOLLTE die Kontexte zwischen der Menge der Request-Objekte und der resultierenden Menge der Response-Objekte anhand des id-Elements in jedem Objekt 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 aus einem einzelnen Response-Objekt bestehen. Enthält das Response-Array, das an den Client gesendet werden soll, keine Response-Objekte, DARF der Server KEIN leeres Array zurückgeben und sollte überhaupt nichts zurückgeben.

Beispiele

Syntax:

--> data sent to Server
<-- data sent to Client

RPC-Aufruf 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-Aufruf 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 Mitteilung:

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

RPC-Aufruf einer nicht vorhandenen Methode:

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

RPC-Aufruf mit ungültigem JSON:

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

RPC-Aufruf mit ungültigem Request-Objekt:

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

RPC-Aufruf „Batch“, ungültiges JSON:

--> [ {"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-Aufruf mit einem leeren Array:

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

RPC-Aufruf mit einem ungültigen Batch (der jedoch nicht leer ist):

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

RPC-Aufruf 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-Aufruf „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-Aufruf „Batch“ (alle Benachrichtigungen):

--> [
 {"jsonrpc": "2.0", "method": "notify_sum", "params": [1,2,4]},
 {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
]
<-- //Nothing is returned for all notification batches

Erweiterungen

Methodennamen, die mit „rpc.“ beginnen, sind für Systemerweiterungen reserviert und DÜRFEN NICHT für andere Zwecke verwendet werden. Jede Systemerweiterung ist in einer entsprechenden Spezifikation definiert. Alle Systemerweiterungen sind OPTIONAL.

Copyright (C) 2007–2010 der JSON-RPC-Arbeitsgruppe

Dieses Dokument und seine Übersetzungen dürfen zur Implementierung von JSON-RPC verwendet werden; es darf kopiert und an Dritte weitergegeben werden; und abgeleitete Werke, die es kommentieren, anderweitig erläutern oder bei seiner Implementierung helfen, dürfen ganz oder teilweise ohne jegliche Einschränkung erstellt, kopiert, veröffentlicht und verbreitet werden, vorausgesetzt, dass der obenstehende Urheberrechtsvermerk und dieser Absatz in allen derartigen Kopien und abgeleiteten Werken enthalten sind. Das Dokument selbst darf jedoch in keiner Weise verändert werden.

Die oben gewährten eingeschränkten Berechtigungen gelten auf Dauer und werden nicht widerrufen.

Dieses Dokument und die darin enthaltenen Informationen werden „wie besehen“ bereitgestellt, und es wird jegliche ausdrückliche oder stillschweigende Gewährleistung ausgeschlossen, einschließlich, aber nicht beschränkt auf die Gewährleistung, dass die Nutzung der hierin enthaltenen Informationen keine Rechte verletzt, sowie jegliche stillschweigende Gewährleistung der Marktgängigkeit oder der Eignung für einen bestimmten Zweck.