JSON-RPC

Z Wikipedii, wolnej encyklopedii
Skocz do: nawigacja, szukaj

JSON-RPC jest to 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), definujący tylko najbardziej użyteczne typy danych i komendy. JSON-RPC pozwala na powiadomienia (informacje przesyłane do serwera, który nie wymaga odpowiedzi) oraz wielu wywołań możliwość wysyłania do serwera, który możne odpowiadać bez zachowania kolejności.

Historia[edytuj | edytuj kod]

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

Wersja Opis Data
1.0 Original version Obecnie uznawana jako oficjalna [1] 2005
1.1 WD Working Draft 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 w wersji 2.0. 2007-12-27
2.0 Propozycja specyfikacji 2009-05-24
2.0 (Revised) Propozycja specyfikacji 2010-03-26

Użycie[edytuj | edytuj kod]

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[2].


Wszystkie typy transferu są pojedynczymi obiektami, serializowane przy użyciu JSON[3]. 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[edytuj | edytuj kod]

Zapytanie Klienta[edytuj | edytuj kod]

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

Odpowiedź Serwera[edytuj | edytuj kod]

{"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[edytuj | edytuj kod]

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[3].

...
--> {"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)[edytuj | edytuj kod]

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)[edytuj | edytuj kod]

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}

Implementacje[edytuj | edytuj kod]

  • jsonrpc4j implementacja Java JSON-RPC 2.0 wspierająca przesyłanie strumieniowe jak również serwery HTTP. Posiada także obsługę usługi exporter\consumer.
  • json-rpc is a generic java/javascript implementation which integrates well on Android/Servlets/Standalone Java/Javascript/App-Engine applications.
  • php-json-rpc prosta implementacja PHP JSON-RPC 2.0.
  • easyXDM to biblioteka dla międzydomenowych wiadomości z wbudowanym RPC. Biblioteka obsługuje wszystkie przeglądarki przy użyciu mieszanki postMessage, nix, frameElement, window.name i FIM i jest bardzo łatwa w użyciu.
  • Dojo Toolkit offers a broad support for JSON-RPC
  • Pmrpc jest czymś w rodzaju inter-window i Web Worker zdalnym wywołaniem biblioteki procedury JavaScript do użytku w ramach przeglądarek obsługujących HTML5. Pmrpc jest implementacją JSON-RPC używającą HTML5 postMessage API do przesyłu wiadomości.
  • JSON Toolkit implementacja dla Delphi
  • Począwszy od wersji 2.0, XINS wsparcie zarówno JSON i JSON-RPC.
  • qooxdoo zawiera implementację JSON-RPC z opcjonalnymi zapleczami dla języków Java, PHP, Perl and Python.
  • Barracuda Web Server's integrated JSON-RPC online documentation.
  • JSON-RPC implementation in JavaScript zawiera JSON-RPC dla HTTP i dla gniazd TCP/IP
  • JSON/XML-RPC Client and Server Implementations which abstract-away the differences between JSON-RPC and XML-RPC and permit cross-site requests.
  • jpoxy - prosta implementacja Java JSON-RPC zaprojektowana aby być łatwą do zaimplementowania i aby miała możliwość odłonienia metod publicznych w istniejących POJO za pomocą niezawodnej ramy RPC.
  • jabsorb - A lightweight Ajax/Web 2.0 JSON-RPC Java framework rozszeżający protokół JSON-RPC o dodatkowe ORB funkcjonalności takie jak obsługa odwołań cyklicznych
  • JSON-RPC implementation in Java JavaScript do Java AJAX - biblioteka komunikacji (teraz połączona jabsorb.)
  • Jettison - biblioteka Java
  • LEWOStuff zawiera wsparcie Java dla JSON-RPC również z wsparciem dla WebObjects.
  • implementacje Perl na CPAN
  • JsonRpc-Cpp OpenSource JSON-RPC implementacja C++
  • TclSOAP zawiera wsparcie Tcl dla JSON-RPC w dodatku SOAP i XML-RPC.
  • Pyjamas zawiera implementację klienta JSONRPC standard (Pyjamas jest frameworkiem gdzie aplikacje są pisane w Python ale kompilowane do Javascript).
  • Zope 3 JSON-RPC implementacja JSON RPC oparta na Python - serwera i klienta dla Zope 3
  • JQuery JSON-RPC Serverto jest JSON-RPC server, specjalnie zrobiony do pracy z Zend Framework JSON RPC Server. Zend Framework JSON-RPC server jest lekko poza specyfikacją, a zatem to nie jest praca z innymi serwerami JSON-RPC.
  • jsonrpc2php to PHP5 BSD'd JSON-RPC 2.0 Core class and example Server
  • jsonrpclib to JSON-RPC moduł klienta dla Python.
  • JSON-RPC 2.0 Base minimalna biblioteka Java do parsowania, reprezentowania i serializacji wiadomości JSON-RPC 2.0 (open source).
  • JSON-RPC 2.0 Client to biblioteka Java do nawiązywania klient sesji z serwerem JSON-RPC 2.0 (open source).
  • JSON-RPC 2.0 Server to prosty framework Java do przetwarzania zapytań JSON-RPC 2.0 i notyfikacji (open source).
  • JSON-RPC 2.0 Shell do sprawdzenia, testowania i debugowania zdalnego JSON-RPC usługi web 2.0 (komercyjna).
  • Synopse SQLite3 database Framework Open Source Delphi database access, User Interface generation, reporting, i18n in Client/Server AJAX/RESTful model.
  • Objective-C DeferredKit zawiera klienta JSON-RPC 1.0.
  • java-json-rpc JSON-RPC 2.0 implementacja dla serwerów J2EE.
  • lib-json-rpc JSON-RPC 2.0 implementacja na servlet, client, javascript
  • simplejsonrpc Inny prosty JSON-RPC 2.0 Servlet.
  • Tivoka Zorientowana obiektowo implementacja klienta i serweru JSON-RPC 2.0 dla PHP
  • junior PHP client/server biblioteka dla JSON-RPC 2.0
  • json-rpc-php PHP client/server biblioteka dla JSON-RPC 2.0
  • jimson JSON-RPC 2.0 klient i serwer dla Ruby
  • The Wakanda platform includes a JSON-RPC 2.0 client in its Ajax Framework and a JSON-RPC 2.0 service in Server-Side JavaScript
  • Phobos to implementacja JSON-RPC 2.0 dla Qt/C++. Można go używać do wysyłania i odbierania wiadomości na dowolnej warstwie komunikacji (są klasy TCP i HTTP, gotowe do użycia).
  • Deimos to implementacja JSON-RPC 1.0 i 2.0 dla nodejs/javascript (server-side).
  • Inna implementacja PHP protokołu 2.0 z "dot magic" dla php (= obsługa grupowania metod i oddzielenie przez kropki)


Oficjalna strona domowa[4] zawiera linki do implementacji.

Zobacz też[edytuj | edytuj kod]

Przypisy

Linki zewnętrzne[edytuj | edytuj kod]