Přehled
JSON-RPC je bezstavový, odlehčený protokol vzdáleného volání procedur (RPC). Tato specifikace definuje především několik datových struktur a pravidla pro jejich zpracování. Je transportně agnostická v tom smyslu, že tyto koncepty lze používat v rámci jednoho procesu, přes sokety, přes http nebo v mnoha různých prostředích pro předávání zpráv. Používá JSON (RFC 4627) jako dátový formát.
Je navržen tak, aby byl jednoduchý!
Pravidla
Klíčová slova "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" a "OPTIONAL" v tomto dokumentu je třeba interpretovat tak, jak je popsáno v dokumentu RFC 2119.
Protože JSON-RPC využívá JSON, má stejný typ systému (viz http://www.json.org nebo RFC 4627). JSON může reprezentovat čtyři primitivní typy (řetězce, čísla, logické symboly a 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 některý ze strukturovaných typů JSON. Kdykoli se v tomto dokumentu odkazuje na jakýkoli typ JSON, první písmeno se vždy píše s velkým písmenem: Object, Array, String, Number, Boolean, Null. True a False se rovněž píší velkými písmeny.
Všechny názvy členů vyměňované mezi klientem a serverem, které se berou v úvahu pro porovnávání jakéhokoli druhu, by měly být považovány za rozlišující velká a malá písmena. Termíny funkce, metoda a procedura lze považovat za zaměnitelné.
Klient je definován jako původce objektů Request a zpracovatel objektů Response.
Server je definován jako původce objektů Response a zpracovatel objektů Request.
Jedna implementace této specifikace může snadno plnit obě tyto role, a to i současně, pro jiné různé klienty nebo stejného klienta. Tato specifikace se touto vrstvou složitosti nezabývá.
Kompatibilita
Objekty JSON-RPC 2.0 Request a Response nemusí fungovat se stávajícími klienty nebo servery JSON-RPC 1.0. Je však snadné tyto dvě verze rozlišit, protože verze 2.0 má vždy člen s názvem "jsonrpc" s hodnotou String "2.0", zatímco verze 1.0 tento člen nemá. Většina implementací verze 2.0 by měla zvážit pokus o zpracování objektů verze 1.0, i když ne aspekty peer-to-peer a napovídání tříd verze 1.0.
Předmět požadavku
Volání rpc je reprezentováno odesláním objektu Request na server. Objekt Request má následující členy:
jsonrpc - Řetězec určující verzi protokolu JSON-RPC. MUSÍ být přesně "2.0".
method - Řetězec obsahující název metody, která má být vyvolána. Názvy metod začínající slovem rpc následované znakem tečky (U+002E nebo ASCII 46) jsou vyhrazeny pro interní metody a rozšíření rpc a NESMÍ se používat pro nic jiného.
params - Strukturovaná hodnota, která obsahuje hodnoty parametrů, které se použijí při volání metody. Tento člen MŮŽE být vynechán.
id -Identifikátor vytvořený klientem, který MUSÍ obsahovat řetězec, číslo nebo hodnotu NULL, pokud je zahrnuta. Pokud není obsažen, předpokládá se, že se jedná o oznámení. Hodnota by obvykle neměla být NULL [1] a čísla by NEMĚLA obsahovat zlomkové části [2].
Server MUSÍ odpovědět stejnou hodnotou v objektu Response, je-li zahrnuta. Tento člen se používá ke korelaci kontextu mezi oběma objekty.
[1] Nedoporučuje se používat hodnotu Null jako hodnotu pro člen id v objektu Request, protože tato specifikace používá hodnotu Null pro Responses s neznámým id. Také proto, že JSON-RPC 1.0 používá hodnotu id Null pro oznámení, což by mohlo způsobit zmatek při manipulaci.
[2] Problematické mohou být zlomkové části, protože mnoho desetinných zlomků nelze přesně reprezentovat jako binární zlomky.
Notifikace
Oznámení je objekt požadavku bez členu "id". Objekt Request, který je Notification, znamená, že klient nemá zájem o odpovídající objekt Response, a proto nemusí být klientovi vrácen žádný objekt Response. Server NESMÍ odpovídat na oznámení, včetně těch, která jsou součástí dávkového požadavku.
Oznámení nelze z definice potvrdit, protože nemají objekt Response, který by měl být vrácen. Klient jako takový by se nedozvěděl o žádných chybách (jako např. "Invalid params.", "Internal error.").
Struktura parametrů
Pokud jsou parametry pro volání rpc uvedeny, MUSÍ být poskytnuty jako strukturovaná hodnota. Buď podle polohy prostřednictvím pole, nebo podle jména prostřednictvím objektu.
- by-position: params MUSÍ být pole obsahující hodnoty v pořadí očekávaném serverem.
- by-name: params MUSÍ být Object s názvy členů, které odpovídají názvům parametrů očekávaným Serverem. Absence očekávaných názvů MŮŽE vést ke generování chyby. Názvy MUSÍ přesně odpovídat očekávaným parametrům metody, včetně velkých a malých písmen.
Předmět odpovědi
Při volání rpc MUSÍ server odpovědět odpovědí, s výjimkou případů oznámení. Odpověď je vyjádřena jako jeden objekt JSON s následujícími členy:
jsonrpc - Řetězec určující verzi protokolu JSON-RPC. MUSÍ být přesně "2.0".
result - Tento člen je v případě úspěchu VYŽADOVÁN.
Tento člen NESMÍ existovat, pokud došlo k chybě při volání metody.
Hodnota tohoto členu je určena metodou vyvolanou na serveru.
error - Tento člen je POŽADOVÁN při chybě.
Tento člen NESMÍ existovat, pokud při vyvolání metody nedošlo k chybě.
Hodnota tohoto členu MUSÍ být Objekt podle definice v oddíle 5.1.
id - Tento člen je POŽADOVÁN.
MUSÍ být stejný jako hodnota členu id v objektu požadavku.
Pokud došlo k chybě při zjišťování id v objektu Request (např. Parse error/Invalid Request), MUSÍ být NULL.
MUSÍ být zahrnut buď člen result, nebo člen error, ale NESMÍ být zahrnuty oba členy.
Chybný objekt
Pokud dojde při volání rpc k chybě, objekt Response MUSÍ obsahovat člen error s hodnotou, která je Object s následujícími členy:
code - Číslo, které označuje typ chyby, k níž došlo.
MUSÍ to být celé číslo.
message - Řetězec, který obsahuje krátký popis chyby.
Zpráva MUSÍ být omezena na jednu stručnou větu.
data - Primitivní nebo strukturovaná hodnota, která obsahuje další informace o chybě.
Může být vynechána.
Hodnotu tohoto členu definuje server (např. podrobné informace o chybě, vnořené chyby atd.).
Kódy chyb od -32768 do -32000 včetně jsou vyhrazeny pro předem definované chyby. Každý kód v tomto rozsahu, který není výslovně definován níže, je vyhrazen pro budoucí použití. Chybové kódy jsou téměř stejné jako kódy navržené pro XML-RPC na následující url adrese: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php
| kód | zpráva | význam |
|---|---|---|
| -32700 | Chyba parsování Neplatný požadavek Metoda nebyla nalezena Neplatné parametry Interní chyba Chyba serveru |
Server přijal nesprávný JSON. Při zpracování textu JSON došlo na serveru k chybě. |
| -32600 | Neplatný požadavek | Odeslaný JSON není platný předmět požadavku. |
| -32601 | Metoda nebyla nalezena | Metoda neexistuje / není k dispozici. |
| -32602 | Neplatné parametry | Neplatný(é) parametr(y) metody. |
| -32603 | Interní chyba | Interní chyba JSON-RPC. |
| -32099 to -32000 | Chyba serveru | Vyhrazeno pro chyby serveru definované implementací. |
Zbytek prostoru je k dispozici pro chyby definované aplikací.
Série
Pokud chce klient odeslat několik objektů požadavků najednou, MŮŽE odeslat pole naplněné objekty požadavků.
Server by měl odpovědět po zpracování všech dávkových objektů Požadavků polem obsahujícím odpovídající objekty Odpovědí. Pro každý objekt Request by měl existovat objekt Response, s výjimkou toho, že pro oznámení by neměly existovat žádné objekty Response. Server MŮŽE zpracovávat dávkové volání rpc jako sadu souběžných úloh, které zpracovává v libovolném pořadí a s libovolnou šířkou paralelismu.
Objekty Response vracené z dávkového volání MOHOU být vráceny v libovolném pořadí v rámci pole. Klient MUSÍ porovnávat kontexty mezi množinou objektů Request a výslednou množinou objektů Response na základě členu id v rámci každého objektu.
Pokud se samotné dávkové volání rpc nepodaří rozpoznat jako platný JSON nebo jako pole s alespoň jednou hodnotou, MUSÍ být odpovědí serveru jediný objekt Response. Pokud nejsou v poli Response obsaženy žádné objekty Response, jak má být odesláno klientovi, NESMÍ server vrátit prázdné pole Array a neměl by vrátit vůbec nic.
Příklady
Syntax:
--> data sent to Server <-- data sent to Client
výzva 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}
výzva 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}
a Notifikace:
--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}
--> {"jsonrpc": "2.0", "method": "foobar"}
rpc call of non-existent method:
--> {"jsonrpc": "2.0", "method": "foobar", "id": "1"}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Procedure not found."}, "id": "1"}
výzva rpc s neplatným JSON:
--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error."}, "id": null}
výzva rpc s neplatným předmětem požadavku:
--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}
rpc hromadní výzva, 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}
výzva rpc s prázdným polem Array:
--> []
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}
volání rpc s chybnou skupinou (ale ne prázdnou):
--> [1]
<-- [ {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null} ]
rpc sériová výzva:
--> [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 výzva série:
--> [
{"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 hromadní výzva (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 začínající rpc. jsou vyhrazeny pro systémová rozšíření a NESMÍ se používat pro nic jiného. 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
Tento dokument a jeho překlady mohou být použity k implementaci JSON-RPC, mohou být kopírovány a poskytovány ostatním a odvozená díla, která jej komentují nebo jinak vysvětlují nebo pomáhají při jeho implementaci, mohou být připravována, kopírována, publikována a šířena, celá nebo po částech, bez jakéhokoli omezení, za předpokladu, že výše uvedená poznámka o autorských právech a tento odstavec jsou uvedeny na všech takových kopiích a odvozených dílech. Tento dokument samotný však nesmí být žádným způsobem upravován.
Výše uvedená omezená oprávnění jsou časově neomezená a nelze je odvolat.
Tento dokument a informace v něm obsažené jsou poskytovány "TAK, JAK JSOU", a VŠECHNY ZÁRUKY, VÝSLOVNÉ I NEVYJÁDŘENÉ, JSOU VYLOUČENY, VČETNĚ, ALE NEOMEZENĚ, ZÁRUKY, ŽE POUŽITÍM INFORMACÍ V TOMTO DOKUMENTU NEBUDE PORUŠENO ŽÁDNÉ PRÁVO, ANI ŽÁDNÉ NEVYJÁŘENÉ ZÁRUKY PRODEJNOSTI NEBO VHODNOSTI PRO URČITÝ ÚČEL.