JSON-RPC

JSON-RPC je protokol pro vzdálené volání procedur (RPC) v rámci kódování javascriptovým objektovým zápisem (JSON). Jedná se tedy o jednoduchý protokol, který se, podobně jako XML-RPC (kde je ale místo JSONu využíváno XML) zaměřuje na komunikaci pro účely distribuovaných výpočtů. Protokol umožňuje jak asynchronní komunikaci, neboť zprávy mohou obsahovat ID, které určuje jejich vztah, tak jednostranné oznamování, tedy zaslání zprávy, na kterou není vyžadována odpověď.

JSON-RPC 1.0

První verze specifikace 1.0 byla vydána v roce 2005. Definovala komunikaci ve formě požadavku (request), odpovědi (response) a notifikace (notification), což je požadavek bez odpovědi.

Každý požadavek v JSON-RPC je JSON, který obsahuje tyto prvky:

• method – řetězec obsahující název metody, která se má provést
• params – pole parametrů metody
• id – identifikace požadavku; může být libovolného typu, s tím, že id stejné hodnoty bude vráceno v odpovědi

Odpověď v JSON-RPC je JSON, který obsahuje prvky:

• result – objekt, jež je výsledkem volané metody; skončila-li operace chybou, musí být null
• error – objekt typu Error, pokud volaná metoda skončila chybou – v opačném případě musí být null
• id – identifikace požadavku

Notifikace v JSON-RPC je JSON, který má stejné prvky jako požadavek, s tou výjimkou, že je id je null. Server na notifikace neposílá odpověď.

JSON-RPC 2.0

Poslední verzí je revidovaná 2.0 vydaná v březnu 2010. Oproti verzi 1.0 se liší následujícím způsobem: V požadavcích:

• přibyl prvek jsonrpc, který musí mít hodnotu „2.0“
• methody začínající na „rpc.“ jsou rezervovány pro interní účely
• prvek params může být vynechán u metod, které nemají parametry. Je-li uveden, musí to být buď asociativní pole nebo hash (pole s číselnými indexy).
• prvek id, je-li zadán, musí být buď číslo nebo řetězec nebo null. Není-li zadán, předpokládá se, že se jedná o notifikaci.
• požadavky lze poslat dávkově, v poli

V odpovědích:

• přibyl prvek jsonrpc, který musí mít hodnotu „2.0“
• prvek result je povinný při úspěchu a naopak při chybě musí chybět.
• prvek error je povinný při chybě a musí být objekt, naopak při úspěchu musí chybět
• prvek id musí být null, pokud se nepodařilo detekovat id požadavku
• odpovědi poslané v dávce požadavků mohou být odeslány také v dávce

Případná chyba je objekt, který má následující prvky:

• code číslo indikující typ chyby
• message řetězec s krátkým popisem chyby
• data dodatečné informace; mohou být vynechána

Chybové kódy -32600 až -32768 jsou rezervovány pro standardní chybové situace.

Odkazy

Reference

V tomto článku byl použit překlad textu z článku JSON-RPC na německé Wikipedii.

Externí odkazy

• Oficiální stránky protokolu (anglicky)

Portály: Internet