JSON-RPC 2.0 Specifikace

Překlad:: 2012-12-26 (na základě originálu z 2010-03-26)
Autor překladu:: Pavel Železný <[email protected]>

Obsah:

Přehled
Konvence
Kompatibilita
Objekt požadavku (Request)
1. Notifikace
2. Struktura parametrů
Objekt odpovědi (Response)
1. Objekt chybné odpovědi (Error)
Hromadný požadavek
Příklady
Rozšíření

1 Přehled

JSON-RPC je bezstavový a lehký protokol pro vzdálené volání procedur (RPC). Tato specifikace primárně slouží, jako definice několika datových struktur a pravidel pro jejich zpracování. Koncept je nezávislý na použitém komunikačním protokolu, takže jeho zpracování může být stejné přes sokety, přes http i v mnoha jiných prostředích fungujících na principu zasílání zpráv. Používá JSON (RFC 4627) jako datový formát.
Je navržen tak, aby byl jednoduchý!

2 Konvence

Slova označující příkazy a zákazy ("MUSÍ", "NESMÍ", "MĚLO BY", "NEMĚLO BY", "VYŽADOVÁNO", "DOPORUČENO", "SMÍ", a "VOLITELNĚ") použitá v tomto dokumentu jsou chápána tak, jak jsou popsána v dokumentu RFC 2119.
Od počátku protokolu JSON-RPC se používá formát JSON (viz http://www.json.org nebo RFC 4627). JSON může reprezentovat čtyři základní datové typy (Textový řetězec, Číslo, Booleovská hodnota, a NULL) a dva strukturované datové typy (Objekt a Pole). Označení "Základní datový typ" použité v této specifikaci odkazuje právě na čtyři základní datové typy formátu JSON. Označení "Strukturovaná hodnota" použité v této specifikaci odkazuje právě na strukturované datové typy formátu JSON. Kdykoliv se v tomto dokumentu odkazuje na jakýkoliv datový typ formátu JSON, je první písmeno vždy psáno kapitálkami: Objekt, Pole, Textový řetězec, Číslo, Booleovská hodnota, Null. Hodnoty Pravda a Nepravda jsou rovněž označeny kapitalizovaným prvním písmenem.
Všechna jména členských proměnných vyměněných mezi Klientem a Serverem, která jsou jakýmkoliv způsobem porovnávána, by měla být považována za citlivá na velikost písmen. Termíny funkce, metoda a procedura mohou být považovány za zaměnitelné.
Klient je definován jako tvůrce objektů Požadavků a zpracovatel objektů Odpovědí.
Server je definován jako tvůrce objektů Odpovědí a zpracovatel objektů Požadavků.

Jedna implementace této specifikace může vyhovovat oběma rolím a to i ve stejný. Tato specifikace však neřeší takovouto úroveň komplexity.

3 Kompatibilita

Objekty Požadavků a objekty Odpovědí protokolu JSON-RPC 2.0 nesmí fungovat se stávajícími JSON-RPC 1.0 klienty nebo servery. Je však snadné rozlišit obě verze díky výskytu prvku "jsonrpc", s Textovým řetězcem "2.0", který se na rozdíl od verze 1.0 vyskytuje ve všech objektech Požadavků i Odpovědí. Většina implementací verze 2.0 by měla zvážit snahu o zpracování objektů verze 1.0, i přes aspekty architektury peer-to-peer a technologie napovídání tříd z verze 1.0.

4 Objekt požadavku (Request)

Volání rpc je reprezentováno odesláním objektu Požadavku na Server. Objekt Požadavku obsahuje následující prvky:

jsonrpc: Textový řetězec označující verzi protokolu JSON-RPC. MUSÍ být přesně "2.0".
method: Textový řetězec obsahující jméno metody, která má být zavolána. Název metody začínající slovem rpc a následovaný znakem tečky (U+002E nebo ASCII 46) je vyhrazený pro interní rpc metody a rozšíření a NESMÍ být použit jakkoliv jinak.
params: Strukturovaná hodnota (Objekt a Pole) udržující hodnoty parametrů předané metodě při jejím volání. Tento prvek SMÍ být vynechán.
id: Identifikátor stanovený klientem MUSÍ obsahovat Textový řetězec, Číslo, nebo hodnotu NULL když je přítomen. Když není přítomen, lze předpokládat že se jedná o notifikace. Hodnota BY NEMĚLA být NULL [1] a Číslo BY NEMĚLO být zlomkem [2].

Server MUSÍ odpovědět stejnou hodnotou prvku id v objektu Odpovědi, pokud byl přítomen. Tento prvek se používá k upřesnění souvislostí mezi dvěma objekty.

[1] Použití NULL jako hodnoty pro prvek id v objektu Požadavku se nedoporučuje, protože tato specifikace používá hodnotu NULL pro odpovědi s neznámým id. Také proto, že protokol JSON-RPC 1.0 používá NULL jako hodnotu prvku id pro Notifikace a mohlo by to způsobit zmatek v manipulaci.

[2] Zlomek může být problematický, jelikož mnoho zlomků nemá přesnou reprezentaci v binární podobě.

4.1 Notifikace

Notifikace je objekt Požadavku bez prvku "id". Objekt Požadavku typu Notifikace značí, že Klient nejeví zájem o související objekt Odpovědi a proto žádný objekt Odpovědi není odeslán zpět klientovi. Server NESMÍ odpovědět na požadavky typu Notifikace, včetně těch, které jsou součástí hromadného požadavku.
Notifikace nejsou z definice potvrzovány, jelikož nevracejí žádný objekt Odpovědi. Tím pádem není klient varován ani před jakoukoliv chybou (Například: "Invalid params.","Internal error.").

4.2 Struktura parametrů

Jsou-li přítomny, parametry rpc volání MUSÍ být v podobě Strukturované hodnoty. Řazeny svoji pozicí v Poli nebo svým jménem v Objektu.

svoji pozicí: parametry MUSÍ být uchovány v Poli, obsahující hodnoty v tom pořadí v jakém je očekává Server.
svým jménem: parametry MUSÍ být uchovány v Objektu, jehož členské proměnné přesně odpovídají jménům parametrů na Serveru. Absence očekávaného parametru SMÍ skončit návratem objektu Chybné odpovědi. Jméno členské proměnné MUSÍ být přesně stejné, včetně velikosti písmen, jako očekávané jméno parametru metody.

5 Objekt odpovědi (Response)

Když bylo provedeno volání rpc, Server MUSÍ odpovědět objektem Odpovědi, kromně případu zaslání notifikace. Objekt Odpovědi je reprezentován jedním JSON Objektem s následujícími prvky:

jsonrpc: Textový řetězec označující verzi protokolu JSON-RPC. MUSÍ být přesně "2.0".
result: Tento prvek je VYŽADOVÁN při úspěšném zpracování.
Tento prvek NESMÍ existovat, pokud nastala jakákoliv chyba při zpracování.
Hodnota tohoto prvku se řídí výsledkem volání metody na Serveru.
error: Tento prvek je VYŽADOVÁN při chybném zpracování.
Tento prvek je NESMÍ existovat, pokud nenastala žádná chyba při zpracování.
Hodnota tohoto prvku MUSÍ být Objekt definovaný v sekci 5.1.
id: Tento prvek je VYŽADOVÁN.
MUSÍ mít přesně stejnou hodnotu, jaká byla zaslána v příslušném prvku objektu Požadavku.
Pokud nastal jakýkoliv problém při získání hodnoty prvku id z objektu Požadavku (například z důvodu Parse error / Invalid Request), prvek id MUSÍ mít hodnotu NULL.

Jeden z prvků result nebo error MUSÍ být přítomen, oba prvky však přítomné být NESMÍ.

5.1 Objekt chybné odpovědi (Error)

Když rpc volání skončilo chybou, objektu Odpovědi MUSÍ obsahovat prvek error s hodnotou typu Objekt a obsahující následující prvky:

code: Číslo které značí typ chyby, která nastala.
Hodnota MUSÍ být celé číslo.
message: Textový řetězec obsahující krátký popis nastalé chyby.
Zpráva BY MĚLA být omezena do podoby jednoduché věty.
data: Základní datový typ nebo Strukturovaná hodnota obsahující doplňující informace o nastalé chybě.
Prvek SMÍ být vynechán.
Hodnota tohoto prvku je definována na Serveru (např. podrobné informace o chybě, vnořené chyby atd.).

Hodnota prvku code z následujícího rozsahu -32768 až -32000 je rezervována pro předdefinované chyby. Jakýkoliv kód z tohoto rozsahu, který není přesně definován je rezervován pro budoucí použití. Chybové kódy jsou téměř stejné jako v doporučení pro XML-RPC na následující adrese: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

code	message	význam
-32700	Parse error	Server přijal neplatný JSON objekt. Nastala chyba při převodu textu na JSON objekt.
-32600	Invalid Request	Zaslaný JSON objekt není platný objektu Požadavku.
-32601	Method not found	Požadovaná metoda neexistuje nebo není dostupná.
-32602	Invalid params	Neplatný parametr(y) metody.
-32603	Internal error	Vnitřní chyba JSON-RPC serveru.
-32000 až -32099	Server error	Rezervováno pro serverové chyby definované implementací.

Zbytek rozsahu je k dispozici pro chyby definované aplikací.

6 Hromadný požadavek

Pro odeslání více objektů Požadavků ve stejný moment, Klient SMÍ odeslat Pole naplněné objekty Požadavků.
Server BY MĚL odeslat odpověď ve formátu Pole obsahující příslušné objekty Odpovědí, poté co jsou zpracovány všechny objektů Požadavků. Objekt Odpovědi BY MĚL existovat pro každý objekt Požadavku, kromě těch, pro které BY NEMĚL být zaslán Objekt Odpovědi jako například pro Notifikace. Server SMÍ zpracovat hromadné rpc volání jako sadu konkurenčních úkolů a zpracovat je v libovolném pořadí, a s libovolnou šíří paralelního zpracování.
Objekty Odpovědí vrácené při hromadném zpracování v Poli SMÍ být v libovolném pořadí. Klient BY MĚL být schopen propojit objekt Požadavk a příslušný objekt Odpovědi na základě hodnoty prvku id u každého objektu.
Pokud selže rozpoznání hromadného rpc požadavku jako JSON objekt, nebo jako Pole obsahující alespoň jeden prvek, Server MUSÍ odpovědět právě jedním objektem Odpovědi. Pokud není žádný objekt Odpovědi ve výsledném poli odesílaném klientovi, server NESMÍ vrátit prázdné Pole a MĚL BY tedy nevrátit zcela nic.

7 Příklady

Syntaxe:

--> data odeslaná na Server
<-- data odeslaná Klientovi

rpc volání s parametry určenými svoji pozicí:

--> {"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 volání s parametry určenými svým jménem:

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

rpc volání typu Notifikace:

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

rpc volání neexistující metody:

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

rpc volání s neplaným JSON objektem:

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

rpc volání s neplatným objektem Požadavku:

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

rpc volání Hromadného požadavku s neplatným JSON objektem:

--> [
  {"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 volání s prázdným polem:

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

rpc volání Hromadného požadavku s neplatný požadavkem (ale ne prázdným):

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

rpc volání Hromadného požadavku s neplatnými požadavky:

--> [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í Hromadného požadavku:

--> [
        {"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 volání Hromadného požadavku: (všechny požadavky typu Notifikace):

--> [
        {"jsonrpc": "2.0", "method": "notify_sum", "params": [1,2,4]},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]}
    ]
<-- // Nic není vráceno pro všechny požadavky typu Notifikace

8 Rozšíření

Název metody začínající slovem rpc a následovaný znakem tečky (U+002E nebo ASCII 46) je vyhrazený pro interní rpc metody a rozšíření a NESMÍ být použit jakkoliv jinak. Každé systémové rozšíření je definováno v související specifikaci. Všechna systémová rozšíření jsou VOLITELNÁ.

Copyright (C) 2007-2010 by the JSON-RPC Working Group
This document and translations of it may be used to implement JSON-RPC, it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not bemodified in any way.
The limited permissions granted above are perpetual and will not be revoked.
This document and the information contained herein is provided "AS IS" and ALL WARRANTIES, EXPRESS OR IMPLIED are DISCLAIMED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.