JSON-RPC

JSON-RPC – protokół zdalnego wywoływania procedur implementowany zazwyczaj ponad HTTP, który jako dane transportowe wykorzystuje obiekty JSON-a. Jest to bardzo prosty protokół (bardzo podobny do XML-RPC), definiujący tylko najbardziej użyteczne typy danych i komendy. JSON-RPC pozwala na powiadomienia (informacje przesyłane do serwera, nie wymagające odpowiedzi) oraz możliwość wysyłania do serwera wielu wywołań, mogących uzyskać odpowiedź poza kolejnością wysyłki.

Historia

Pierwsza wersja protokołu została przedstawiona w 2005 roku, najnowszą wersję 2.0 ogłoszono w 2010 roku:

Wersja	Opis	Data
1.0	wersja oryginalna – obecnie uznawana jako oficjalna	2005
1.1 WD	wersja robocza – dodaje nazwy parametrów, dodaje konkretne kody błędów i dodaje funkcje introspekcji	2006-08-07
1.1 Alt	sugestia prostego JSON-RPC 1.1 – alternatywna propozycja dla wersji 1.1 WD	2007-05-06
1.2	propozycja – późniejsza korekta tego dokumentu to wersja 2.0 specyfikacji	2007-12-27
2.0	propozycja specyfikacji	2009-05-24
2.0 (Revised)	propozycja specyfikacji	2010-03-26

Użycie

JSON-RPC działa, wysyłając żądanie do serwera, implementując niniejszy protokół. Klient w takim przypadku jest typowo oprogramowaniem, które chce wywołać pojedynczą metodę zdalnego systemu. Wiele parametrów wejściowych może być przekazanych do zdalnej metody w postaci tablicy lub obiektu, natomiast sama metoda może również zwracać wiele danych wyjściowych (To zależy od realizowanych wersji). Zdalna metoda jest wywoływana przez wysłanie zapytania do zdalnej usługi za pomocą HTTP.

Kiedy używamy HTTP, to content-type może być definiowany jako application/json.

Wszystkie typy transferu są pojedynczymi obiektami, serializowane przy użyciu JSON. Zapytanie jest wywołaniem określonej metody dostarczonej przez zdalny system. Musi zawierać trzy określone właściwości:

• method – String z nazwą metody do wywołania.
• params – Tablica obiektów, które będą przekazywane jako parametry do zdefiniowanej metody.
• id – Wartość dowolnego typu, która jest używana do dopasowania reakcji do zapytania, na które udzielana jest odpowiedź.

Odbiorca musi udzielić prawidłowej odpowiedzi na wszystkie otrzymane zapytania. Odpowiedź musi zawierać właściwości wymienione poniżej:

• result – Dane zwrócone przez wywoływane metody. Jeśli wystąpił błąd podczas wywoływania metody, wartość ta musi wynosić null.
• error – Określony kod błędu (jeśli wystąpił błąd podczas wywoływania metody), w przeciwnym razie null.
• id – Id zapytania, na które odpowiada.

Ponieważ istnieją sytuacje, w których odpowiedź nie jest potrzebna, a wręcz jest niepożądana, zostały wprowadzone zawiadomienia. Zawiadomienie jest podobne do zapytania. Różnica polega na braku id, które nie jest potrzebne, ponieważ nie oczekujemy odpowiedzi. W tym przypadku własności id powinny być pominięte (wersja 2.0) lub ustawione na null (wersja 1.0).

Przykłady

Zapytanie Klienta

 {"id": 1, "jsonrpc":"2.0", "method": "echo", "params": ["hello"]}

Odpowiedź Serwera

{"id": 1, "jsonrpc":"2.0", "error": null, "result": "hello"}

Istnieje także możliwość wywoływania wielu wywołań funkcji, wtedy poszczególne zapytanie przekazywane są w tablicy, a serwer zwraca tablicę odpowiedzi.

W poniższych przykładach --> oznacza dane wysyłane do serwisu (zapytanie), podczas gdy <-- oznacza dane pochodzące z serwisu (chociaż tym kierunku często nazywa się to odpowiedzią, w architekturze klient-serwer w zależności od wersji JSON-RPC nie musi to jednak oznaczać odpowiedzi na zapytanie).

Wersja 1.0

Proste zapytanie i odpowiedź:

--> { "method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- { "result": "Hello JSON-RPC", "error": null, "id": 1}

W tym przykładzie przedstawiono części komunikatu na przykładzie zastosowania czatu. Usługa czatu wysyła powiadomienia dla każdej wiadomości, którą klient powinien otrzymać. Klient wysyła zapytania do czatu i oczekuje, pozytywnej odpowiedzi, że wiadomość została zapisana.

...
--> {"method": "postMessage", "params": ["Hello all!"], "id": 99}
<-- {"result": 1, "error": null, "id": 99}
<-- {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
<-- {"method": "handleMessage", "params": ["user3", "sorry, gotta go now, ttyl"], "id": null}
--> {"method": "postMessage", "params": ["I have a question:"], "id": 101}
<-- {"method": "userLeft", "params": ["user3"], "id": null}
<-- {"result": 1, "error": null, "id": 101}
...

Ponieważ pole params jest tablicą obiektów, następujący format również jest poprawny:

{
 "method": "methodnamehere",
 "params": [
            {
             "firstparam": "this contains information of the firstparam.",
             "secondparam": 1121211234,
             "thirdparam": "this contains information of the thirdparam."
            },
            {
             "fourthparam": "this is already a different object.",
             "secondparam": "there can be same name fields in different objects.",
             "thirdparam": "this contains information of the thirdparam."
            }
           ],
 "id": 1234
}

Wersja 1.1 (Working Draft)

Format zawartości zapytania może być przedstawiona jak przykład poniżej:

{
"version": "1.1",
"method": "confirmFruitPurchase",
"id": "194521489",
"params": [
    [ "apple", "orange", "pear" ], 
    1.123 
]
}

Format odpowiedzi może wyglądać tak:

{
"version": "1.1",
"result": "done",
"error": null,
"id": "194521489"
}

Wersja 2.0 (Propozycja Specyfikacji)

Procedura Call z parametrami pozycyjnymi:

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

Procedura Call z nazwami parametrów:

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

Notyfikacja:

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

--> {"jsonrpc": "2.0", "method": "foobar"}

Procedura Call procedury nieistniejącej:

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

Procedura Call z nieprawidłowym JSON:

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

Procedura Call z nieprawidłowym JSON-RPC:

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

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

Zobacz też

• JSON
• Zdalne wywołanie procedury

Linki zewnętrzne

• JSON-RPC. [dostęp 2010-12-29]. [zarchiwizowane z tego adresu (2014-12-29)]. (ang.).
• JSON-RPC discussion group. (ang.).