JSON-RPC
JSON-RPC (сокр. от англ. JavaScript Object Notation Remote Procedure Call — JSON-вызов удаленных процедур) — протокол удаленного вызова процедур, использующий JSON для кодирования сообщений. Это очень простой протокол (очень похожий на XML-RPC), определяющий только несколько типов данных и команд. JSON-RPC поддерживает уведомления (информация отправляемая на сервер не требует ответа) и множественные вызовы.
Краткая история
[править | править код]| Версия | Описание | Дата |
|---|---|---|
| 1.0 | Оригинальная версия в настоящее время считается официальной[1]. | 2005 |
| 1.1 WD | Рабочий черновик
Добавлены именованные параметры, специфичные коды ошибок и функции самонаблюдения. |
2008-08-07 |
| 1.1 Alt | Соглашение о простом JSON-RPC 1.1
Альтернативное предложение к 1.1 WD. |
2007-05-06 |
| 1.1 Object Specification | Объектная спецификация Альтернативное предложение к 1.1 WD/1.1 Alt | 2007-07-30 |
| 1.2 | Предложение Поздняя версия этого документа была переименована в 2.0. | 2007-12-27 |
| 2.0 | Предложение спецификации | 2009-05-24 |
| 2.0 (Revised) | Спецификация | 2010-03-26 |
Использование
[править | править код]JSON-RPC работает отсылая запросы к серверу, реализующему протокол. Клиентом обычно является программа, которой нужно вызвать метод на удаленной системе. Множество входных параметров может быть передано удаленному методу, как массив или объект. Метод также может вернуть множество выходных данных (это зависит от реализации). Удаленный метод вызывается отправлением запроса на удаленный сервер посредством HTTP или TCP/IP сокета (начиная с версии 2.0). При использовании HTTP, Заголовок Content-Type определяется как application/json[2].
Все передаваемые данные — простые объекты, сериализованные в JSON[3]. Запрос — Вызов определенного метода, предоставляемого удаленной системой. Он должен содержать три обязательных свойства:
method— Строка с именем вызываемого метода.params— Массив объектов, которые должны быть переданы методу, как параметры.id— Значение любого типа, которое используется для установки соответствия между запросом и ответом.
Сервер должен отослать правильный ответ на каждый полученный запрос. Ответ должен содержать следующие свойства:
result— Данные, которые вернул метод. Если произошла ошибка во время выполнения метода, это свойство должно быть установлено вnull.error— Код ошибки, если произошла ошибка во время выполнения метода, иначеnull.id— То же значение, что и в запросе, к которому относится данный ответ.
Для ситуаций, когда ответ не требуется, были введены уведомления. Уведомление отличается от запроса отсутствием свойства id, которое не требуется, так как не будет передан ответ. В таком случае свойство id может быть пропущено (версия 2.0) или установлено в null (версия 1.0).
Примеры
[править | править код]В данных примерах, --> обозначает данные, отправленные серверу (запрос), а <-- обозначают ответ.
Версия 1.0
[править | править код]Простой запрос и ответ.
--> {"method": "echo", "params": ["Hello JSON-RPC"], "id":1}
<-- {"result": "Hello JSON-RPC", "error": null, "id":1}
Этот пример показывает взаимодействие в приложении чата. Сервер отсылает уведомления о каждом сообщении каждому клиенту, который должен его получить. Клиент отправляет запрос серверу, чтобы отправить сообщение в чат и ждет позитивного ответа, чтобы знать, что сообщение было доставлено.
...
--> {"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}
...
Так как свойство params является массивом объектов, следующий формат является валидным.
{
"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
}
Версия 1.1 (Рабочий черновик)
[править | править код]Формат запроса должен быть примерно следующим:
{
"version": "1.1",
"method": "confirmFruitPurchase",
"id": "194521489",
"params": [
["apple", "orange", "Mangoos"],
1.123
]
}
Формат ответа может быть примерно таким:
{
"version": "1.1",
"result": "done",
"error": null,
"id": "194521489"
}
Версия 2.0
[править | править код]Вызов процедуры с позиционными параметрами:
--> {"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}
Вызов процедуры с именованными параметрами:
--> {"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}
Уведомление:
--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}
--> {"jsonrpc": "2.0", "method": "foobar"}
Вызов несуществующей функции:
--> {"jsonrpc": "2.0", "method": "foobar", "id": 10}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Procedure not found."}, "id": 10}
Вызов процедуры с неправильным JSON:
--> {"jsonrpc": "2.0", "method": "foobar", "params": "bar", "baz"]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}
Вызов процедуры с неправильным 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}
Реализации
[править | править код]| Название | версия JSON-RPC | Описание | Язык(и), Платформы |
|---|---|---|---|
| JSON-RPC.NET | 2.0 | Быстрый JSON-RPC сервер. Поддерживает сокеты, именованные сокеты и HTTP с помощью ASP.NET требует Mono или .NET Framework 4.0. | .NET |
| Jayrock | 1.0 | Серверная реализация JSON-RPC 1.0 для версий 1.1 и 2.0 Microsoft .NET Framework. | .NET |
| jsonrpc-c | 2.0 | Реализация JSON-RPC через TCP сокеты (только сервер). | C |
| libjson-rpc-cpp | 2.0 | C++ JSON-RPC фрэймворк, поддерживающий клиентскую и серверную стороны через HTTP. | C++ |
| Phobos | 2.0 | Реализация для Qt/C++. Абстрагирует уровень передачи данных (готовые к использованию классы для TCP и HTTP). | C++ |
| qjsonrpc | 2.0 | Реализация для Qt/C++. Поддерживает соединения между сообщениями и QObject слотами (как QDBus, qxtrpc) использует новые JSON классы, включенные в Qt5. | C++ |
| JSON Toolkit | 2.0 | Реализация на Delphi | Delphi |
| go/net/rpc | ? | Реализация JSON-RPC стандартной библиотеки Go | Go |
| jsonrpc4j | 2.0 | Java реализация JSON-RPC 2.0 поддерживает как сокеты, так и HTTP соединение. | Java |
| json-rpc | 1.0 | Базовая Java/JavaScript реализация, которая хорошо интегрируется в Android/Servlets/Standalone Java/JavaScript/App-Engine приложения. | Java / JavaScript |
| jpoxy | 2.0 | Простая Java реализация JSON-RPC созданная для упрощения реализации доступа к POJOs через сырой RPC фрэймворк. | Java |
| JSON Service | 2.0 | JSON-RPC серверная реализацияс поддержкой Service Mapping Description. Хорошо интегрируется с Dojo Toolkit и Spring Framework. | Java |
| JSON-RPC 2.0 | 2.0 | Легкая Java library для разбора и сериализации JSON-RPC 2.0 сообщений (open source). Несколько реализация на сайте. (Base, Client, Shell, …) | Java |
| java-json-rpc | 2.0 | Реализация для J2EE серверов. | Java |
| lib-json-rpc | 2.0 | Реализация servlet, client, JavaScript | Java |
| simplejsonrpc | 2.0 | Простой JSON-RPC 2.0 Servlet, обслуживающий методы класса. | Java |
| gson-rmi | 2.0 | Легковесный, независимый от способа передачи RMI фрэймворк разработанный для распределенных вычислений. | Java |
| jsonrpcjs | 2.0 | JavaScript клиентская библиотека для JSON-RPC 2.0, Не имеет зависимостей. | JavaScript |
| easyXDM | 2.0 | Библиотека для cross-domain соединений с поддержкой RPC. Поддерживает все браузеры postMessage, nix, frameElement, window.name, и FIM, очень проста в использовании. | JavaScript |
| Dojo Toolkit | 1.0+ | Предоставляет поддержку JSON-RPC | JavaScript |
| Pmrpc | 2.0 | JavaScript библиотека для использования в HTML5 браузерах. Реализация JSON-RPC, используя HTML5 postMessage API для передачи сообщений. | JavaScript |
| qooxdoo | 2.0 | Имеет JSON-RPC реализацию с опциональными бэк-эндами на Java, PHP, Perl и Python. | JavaScript, Java, PHP, PERL, & Python |
| JSON-RPC Реализация на JavaScript | 2.0 | Поддерживает JSON-RPC через HTTP и TCP/IP. | JavaScript |
| jabsorb | 2.0 | Легковесный Ajax/Web 2.0 JSON-RPC Java фрэймворк, расширяющий JSON-RPC протокол дополнительной ORB функциональностью, такой как поддержка циклических зависимостей. | JavaScript, Java |
| The Wakanda platform | 2.0 | Поддерживает JSON-RPC 2.0 клиент внутри Ajax Framework и JSON-RPC 2.0 сервис в серверном JavaScript | JavaScript |
| Deimos | 1.0+2.0 | Серверная реализация для Node.js/JavaScript. | JavaScript |
| Barracuda Web Server | 2.0 | Barracuda Web Server’s интегрированный | Lua |
| DeferredKit | 1.0 | Поддерживает JSON-RPC 1.0 клиент. | Objective-C |
| Demiurgic | 2.0 | JSON-RPC 2.0 клиент для Objective-C | Objective-C |
| Oxen iPhone Commons JSON components | 1.0 | JSON-RPC 1.0 клиент для Objective-C | Objective-C |
| objc-JSONRpc | 2.0 | Objective-c JSON RPC клиент. Поддерживает уведомления, простые вызовы и множественные вызовы. | Objective-C |
| JSON::RPC | 2.0 | Реализация сервера JSON RPC 2.0 | Perl |
| json-rpc-perl6 | 2.0 | Клиент и сервер. | Perl 6 |
| php-json-rpc | 2.0 | Простая PHP реализация JSON-RPC 2.0 через HTTP клиента. | PHP |
| JQuery JSON-RPC Server | 2.0 | JSON-RPC сервер, специально сделанный для работы с Zend Framework JSON RPC Server. | PHP, JavaScript |
| jsonrpc2php | 2.0 | PHP5 JSON-RPC 2.0 базовый класс и пример сервера | PHP |
| tivoka | 1.0 + 2.0 | Универсальный клиент/серверная JSON-RPC библиотека для PHP 5+. | PHP |
| junior | 2.0 | Client/server библиотека для JSON-RPC 2.0 | PHP |
| json-rpc-php | 2.0 | Client/server библиотека для JSON-RPC 2.0 | PHP |
| JSONRpc2 | 2.0 | Реализация с «dot magic» для PHP (= поддержка группировки методов и разделения точками) | PHP |
| GetResponse jsonRPCClient | 2.0 | Объектно-ориентированная реализация клиента | PHP |
| zoServices | 2.0 | PHP, Node.js и JavaScript реализация JSON-RPC 2.0 | PHP, JavaScript, Node.js |
| json-rpc2php | 2.0 | Серверная и клиентская реализация для PHP. Содержит JavaScript клиент, использующий jQuery | PHP, JavaScript |
| jsonrpc-php | 2.0 | JSON-RPC реализация для PHP | PHP |
| php-json-rpc | 2.0 | Реализация JSON-RPC 2.0. | PHP |
| Django JSON-RPC 2.0 | 2.0 | JSON-RPC сервер для Django | Python |
| Pyjamas | JSON-RPC клиентская реализация. | Python | |
| Zope 3 | 1.1 | JSON RPC реализация для Zope 3 | Python |
| jsonrpclib | 2.0 | JSON-RPC клиентский модуль для Python. | Python |
| tornadorpc | 2.0 | Поддерживает JSON-RPC требует Tornado web server. | Python |
| tinyrpc | 2.0 | Поддерживает JSON-RPC через TCP, WSGI, ZeroMQ и др. Разделяет передачу данных от обработки сообщений, может работать без пересылки сообщений. | Python |
| jsonrpc | 2.0 | JSON-RPC 2.0 для Python + Twisted. | Python |
| bjsonrpc | 1.0+ | Реализация через TCP/IP (асинхронная, двунаправленная) | Python |
| Barrister RPC | 2.0 | JSON-RPC реализация клиента и сервера | Python, Ruby, JavaScript (Node.js + web browser), PHP, Java |
| pyramid_rpc | 2.0 | Гибкая JSON-RPC реализация интегрированная в Pyramid web application. Работает с Pyramid’s системой авторизации. | Python |
| rjr | 2.0 | JSON-RPC через TCP/UDP, HTTP, WebSockets, AMQP, и прочие. | Ruby (EventMachine) сервер с Ruby и JavaScript клиентами. |
| jimson | 2.0 | Клиент и сервер для Ruby | Ruby |
| JSON-RPC Objects | 1.0+ | Реализация только объектов (без клиента и сервера). | Ruby |
| JSON-RPC RT | 2.0 | Полная поддержка JSON-RPC 2.0 через TCP. | Windows Runtime (WinRT) |
| XINS | 2.0 | С Версии 2.0, поддерживает JSON и JSON-RPC. | XML |
Официальная страница[4] содержит больше реализаций. CPAN список реализаций на Perl.
См. также
[править | править код]- Remote procedure call (RPC);
- SOAPjr — гибрид SOAP и JSON-RPC;
- JSON-WSP — основанный на JSON-RPC протокол.
Примечания
[править | править код]Ссылки
[править | править код]- Официальный сайт
- Официальная страница JSON-RPC 1.0
- JSON-RPC Google группа. Обсуждение связанных с протоколом тем
- JSON-RPC спецификации, ссылки, и пр.