KerioControl – Specifikace JSON-RPC 2.0

Přehled

JSON-RPC je bezstavový, odlehčený protokol pro vzdálené volání procedur (RPC). Tato specifikace především definuje několik datových struktur a pravidla pro jejich zpracování. Je nezávislá na transportním protokolu, což znamená, že tyto koncepty lze použít v rámci stejného procesu, přes sokety, přes HTTP nebo v mnoha různých prostředích pro předávání zpráv. Jako datový formát využívá JSON (RFC 4627).

Je to navrženo tak, aby to bylo jednoduché!

Konvence

Klíčová slova „MUST“, „MUST NOT“, „REQUIRED“, „SHALL“, „SHALL NOT“, „SHOULD“, „SHOULD NOT“, „RECOMMENDED“, „MAY“ a „OPTIONAL“ v tomto dokumentu je třeba vykládat tak, jak je popsáno v RFC 2119.

Jelikož JSON-RPC využívá JSON, má stejný typový systém (viz http://www.json.org nebo RFC 4627). JSON může reprezentovat čtyři primitivní typy (řetězce, čísla, logické hodnoty a hodnotu null) a dva strukturované typy (objekty a pole). Termín „primitivní“ v této specifikaci odkazuje na kterýkoli z těchto čtyř primitivních typů JSON. Termín „strukturovaný“ odkazuje na kterýkoli ze strukturovaných typů JSON. Kdykoli se tento dokument zmiňuje o jakémkoli typu JSON, první písmeno se vždy píše s velkým počátečním písmenem: objekt, pole, řetězec, číslo, logická hodnota, null. Velkými písmeny se píší také hodnoty „true“ a „false“.

U všech názvů členů, které si klient a server vyměňují a které se berou v úvahu při jakémkoli porovnávání, je třeba počítat s rozlišováním velkých a malých písmen. Pojmy „funkce“, „metoda“ a „procedura“ lze považovat za vzájemně zaměnitelné.

Klient je definován jako zdroj objektů Request a zpracovatel objektů Response.
Server je definován jako zdroj objektů Response a zpracovatel objektů Request.

Jedna implementace této specifikace by mohla snadno plnit obě tyto role, a to i současně, a to buď pro různé klienty, nebo pro stejného klienta. Tato specifikace se touto úrovní složitosti nezabývá.

Kompatibilita

Objekty Request a Response ve standardu JSON-RPC 2.0 nemusí fungovat se stávajícími klienty nebo servery podporujícími JSON-RPC 1.0. Mezi těmito dvěma verzemi lze však snadno rozlišit, protože verze 2.0 vždy obsahuje člen s názvem „jsonrpc“ a hodnotou typu String „2.0“, zatímco verze 1.0 tento člen nemá. Většina implementací verze 2.0 by měla zvážit podporu objektů verze 1.0, i když ne v oblasti peer-to-peer komunikace a class hintingu, které jsou charakteristické pro verzi 1.0.

Objekt požadavku

Volání RPC se provádí odesláním objektu Request na server. Objekt Request obsahuje následující členy:

jsonrpc – Řetězec určující verzi protokolu JSON-RPC. MUSÍ mít přesně hodnotu „2.0“.

metoda – Řetězec obsahující název metody, která má být vyvolána. Názvy metod, které začínají slovem „rpc“ následovaným tečkou (U+002E nebo ASCII 46), jsou vyhrazeny pro interní metody a rozšíření protokolu RPC a NESMÍ být použity k žádnému jinému účelu.

params – Strukturovaná hodnota, která obsahuje hodnoty parametrů, které se mají použít při volání metody. Tento člen MŮŽE být vynechán.

id – Identifikátor stanovený klientem, který MUSÍ obsahovat řetězec, číslo nebo hodnotu NULL, pokud je uveden. Není-li uveden, předpokládá se, že se jedná o oznámení. Hodnota by za normálních okolností neměla být nulová [1] a čísla by neměla obsahovat desetinné části [2]

Server MUSÍ v objektu Response vrátit stejnou hodnotu, pokud je tato hodnota uvedena. Tento člen slouží ke vzájemnému propojení kontextu mezi těmito dvěma objekty.

[1] Použití hodnoty Null jako hodnoty člena id v objektu Request se nedoporučuje, protože tato specifikace používá hodnotu Null pro odpovědi s neznámým id. Navíc, jelikož JSON-RPC 1.0 používá hodnotu Null pro id v oznámeních, mohlo by to při zpracování vést k nejasnostem.

[2] Zlomky mohou představovat problém, protože mnoho desetinných zlomků nelze přesně vyjádřit jako binární zlomky.

Oznámení

Oznámení je objekt typu Request bez člena „id“. Objekt typu Request, který představuje oznámení, signalizuje, že klient nemá zájem o odpovídající objekt typu Response, a proto není třeba klientovi žádný objekt typu Response vracet. Server NESMÍ na oznámení odpovídat, a to ani v případě, že je součástí hromadného požadavku.

Oznámení nelze ze své podstaty potvrdit, protože neobsahují objekt Response, který by bylo možné vrátit. Klient by tak neměl přehled o případných chybách (jako např. „Neplatné parametry“, „Vnitřní chyba“).

Struktury parametrů

Jsou-li k dispozici, MUSÍ být parametry pro volání RPC zadány jako strukturovaná hodnota. A to buď podle pozice prostřednictvím pole, nebo podle názvu prostřednictvím objektu.

• podle pozice: parametry MUSÍ být pole obsahující hodnoty v pořadí, v jakém je server očekává.
• podle názvu: parametry MUSÍ být objektem, jehož názvy členů odpovídají názvům parametrů očekávaným serverem. Chybějící očekávané názvy MOHOU vést k vygenerování chyby. Názvy MUSÍ přesně odpovídat, včetně velkých a malých písmen, parametrům očekávaným metodou.

Objekt odpovědi

Při provedení volání RPC MUSÍ server odpovědět odpovědí, s výjimkou případů oznámení. Odpověď má podobu jediného objektu JSON s následujícími členy:

jsonrpc – Řetězec určující verzi protokolu JSON-RPC. MUSÍ mít přesně hodnotu „2.0“.

result – Tento člen je POVINNÝ v případě úspěšného provedení.
Tento člen NESMÍ existovat, pokud při volání metody došlo k chybě.
Hodnota tohoto člena je určena metodou volanou na serveru.

chyba – Tento člen je při výskytu chyby POVINNÝ.
Tento člen NESMÍ existovat, pokud při volání nedošlo k vyvolání chyby.
Hodnota tohoto člena MUSÍ být objektem, jak je definováno v oddíle 5.1.

id – Tento člen je POVINNÝ.
MUSÍ se shodovat s hodnotou člena id v objektu Request.
Pokud při detekci id v objektu Request došlo k chybě (např. chyba analýzy/neplatný požadavek), MUSÍ mít hodnotu Null.

MUSÍ být zahrnut buď prvek výsledku, nebo prvek chyby, ale NESMÍ být zahrnuty oba prvky.

Objekt chyby

Pokud při volání RPC dojde k chybě, MUSÍ objekt Response obsahovat člen error, jehož hodnotou je objekt s následujícími členy:

kód – Číslo označující typ chyby, ke které došlo.
Musí se jednat o celé číslo.

zpráva – Řetězec obsahující stručný popis chyby.
Zpráva by MĚLA být omezena na jednu stručnou větu.

data – Primitivní nebo strukturovaná hodnota, která obsahuje doplňující informace o chybě.
Tuto hodnotu lze vynechat.
Hodnota tohoto členu je definována serverem (např. podrobné informace o chybě, vnořené chyby atd.).

Chybové kódy od -32768 do -32000 včetně jsou vyhrazeny pro předdefinované chyby. Jakýkoli kód v tomto rozsahu, který není níže výslovně definován, je vyhrazen pro budoucí použití. Tyto chybové kódy se téměř shodují s kódy doporučenými pro XML-RPC na následující adrese: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

Zbývající část prostoru je k dispozici pro chyby definované aplikací.

Dávka

Chce-li klient odeslat několik objektů typu Request najednou, MŮŽE odeslat pole obsahující tyto objekty.

Server by měl po zpracování všech objektů typu Request v dávce odpovědět polem obsahujícím odpovídající objekty typu Response. Pro každý objekt typu Request by MĚL existovat objekt typu Response, s výjimkou toho, že pro oznámení by NEMĚLY existovat žádné objekty typu Response. Server MŮŽE zpracovat dávkové volání RPC jako sadu souběžných úloh, přičemž je může zpracovávat v libovolném pořadí a s libovolnou mírou paralelismu.

Objekty Response vrácené z hromadného volání MOHOU být v poli vráceny v libovolném pořadí. Klient BY MĚL přiřadit kontexty mezi sadou objektů Request a výslednou sadou objektů Response na základě člena id v každém objektu.

Pokud samotné dávkové volání RPC není rozpoznáno jako platný JSON nebo jako pole obsahující alespoň jednu hodnotu, MUSÍ být odpověď ze serveru tvořena jediným objektem typu Response. Pokud pole Response, které má být odesláno klientovi, neobsahuje žádné objekty typu Response, server NESMÍ vrátit prázdné pole a neměl by vracet vůbec nic.

Příklady

Syntaxe:

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

volání RPC s pozičními parametry:

--> {"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}

Volání RPC s pojmenovanými parametry:

--> {"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}

Oznámení:

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

volání RPC neexistující metody:

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

Volání RPC s neplatným JSON:

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

Volání RPC s neplatným objektem Request:

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

Volání RPC „Batch“, neplatný 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}

Volání RPC s prázdným polem:

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

Volání RPC s neplatným dávkovým záznamem (který však není prázdný):

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

Volání RPC s neplatným 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 volání 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"}
]

Volání RPC „Batch“ (všechna oznámení):

--> [
 {"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

Rozšíření

Názvy metod, které začínají předponou „rpc.“, jsou vyhrazeny pro systémová rozšíření a NESMÍ se používat k žádnému jinému účelu. Každé systémové rozšíření je definováno v příslušné specifikaci. Všechna systémová rozšíření jsou VOLITELNÁ.

Autorská práva (C) 2007–2010 patří pracovní skupině JSON-RPC

Tento dokument a jeho překlady lze použít k implementaci JSON-RPC; lze jej kopírovat a poskytovat dalším osobám; dále lze vytvářet, kopírovat, publikovat a šířit odvozená díla, která jej komentují, jinak vysvětlují nebo napomáhají při jeho implementaci, a to v celku i po částech, bez jakýchkoli omezení, za předpokladu, že na všech takových kopiích a odvozených dílech bude uvedeno výše uvedené upozornění o autorských právech a tento odstavec. Samotný tento dokument však nesmí být žádným způsobem upravován.

Výše udělená omezená oprávnění jsou trvalá a nebudou odvolána.

Tento dokument a informace v něm obsažené jsou poskytovány „tak, jak jsou“, a VŠECHNY VÝSLOVNÉ NEBO MLČKY PŘEDPOKLÁDANÉ ZÁRUKY JSOU VYLOUČENY, VČETNĚ, ALE NE OMEZENĚ NA, JAKÉKOLI ZÁRUKY, ŽE POUŽITÍ INFORMACÍ V TOMTO DOKUMENTU NEPORUŠÍ ŽÁDNÁ PRÁVA, NEBO MLČKY PŘEDPOKLÁDANÉ ZÁRUKY OBCHODOVATELNOSTI NEBO VHODNOSTI PRO URČITÝ ÚČEL.