JSON-RPC

JSON-RPC (сокр. от англ. JSON Remote Procedure Call — JSON-вызов удалённых процедур) — протокол удалённого вызова процедур, использующий JSON для кодирования сообщений. Это очень простой протокол (очень похожий на XML-RPC), определяющий только несколько типов данных и команд. JSON-RPC поддерживает уведомления (информация, отправляемая на сервер, не требует ответа) и множественные вызовы.

## Содержание

* 1 Краткая история
* 2 Использование
* 3 Примеры
* 3.1 Версия 1.0
* 3.2 Версия 1.1 (Рабочий черновик)
* 3.3 Версия 2.0
* 4 Реализации
* 5 См. также
* 6 Примечания
* 7 Ссылки

## Краткая история

[править | править код]

Версия  | Описание  | Дата

|
|

1.0  | Оригинальная версия Архивная копия от 13 марта 2013 на Wayback Machine в настоящее время считается официальной[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
2.0 (Updated)  | Спецификация | 2013.01.04

## Использование

[править | править код]

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}
<-- {"result": 1, "error": null, "id": 101}
--> {"method": "userLeft", "params": ["user3"], "id": null}

...

Так как свойство `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

<2c2e8bac-9c1f-49ba-ba40-9a563ae19b93>

### Версия 1.1 (Рабочий черновик)

[править | править код]

Формат запроса должен быть примерно следующим:

"version": "1.1",
"method": "confirmFruitPurchase",
"id": "194521489",
"params": [
["apple", "orange", "Mongoose"],
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": 1}
<-- {"jsonrpc": "2.0", "result": -19, "id": 1}

Вызов процедуры с именованными параметрами:

--> {"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": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}

Уведомление:

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

Вызов процедуры с неправильной структурой

--> [1,2,3]
<-- {"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 для Microsoft .NET Framework версий 1.1 и 2.0 .  | .NET
System.Data.JsonRpc | 2.0  | Компонент для сериализации и десериализации JSON-RPC 2.0 сообщений для .NET Standard 1.0 и выше.  | .NET Standard
StreamJsonRpc | 2.0  | Библиотека реализующая спецификацию JSON-RPC 2.0 с гибкими возможностями выбора транспортного слоя и сериализаторов  | .NET Standard 2.0
jsonrpc-c | 2.0  | Реализация JSON-RPC через TCP сокеты (только сервер).  | C
libjson-rpc-cpp | 2.0 + 1.0  | C++ JSON-RPC фреймворк, поддерживающий клиентскую и серверную стороны через HTTP.  | C++
Phobos | 2.0 | Реализация для Qt/C++. Абстрагирует уровень передачи данных (готовые к использованию классы для TCP и HTTP). | C++
qjsonrpc | 2.0 | Реализация для Qt/C++. Поддерживает соединения между сообщениями и QObject слотами (как QDBus, qxtrpc). Использует новые JSON классы, включённые в Qt 5. | C++
JSON Toolkit Архивная копия от 13 января 2013 на Wayback Machine | 2.0 | Реализация на Delphi (переименован в SuperObject) | Delphi
SuperObject | 2.0 | Реализация на Delphi (поддержка прекращена 14.12.2018) | Delphi
pascal-jsonrpc-lite | 2.0  | Реализация на Pascal (Lazarus, Delphi)  | Pascal
go/net/rpc | 1.0 | Реализация 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 для разбора и сериализации 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
THETA-RPC | 2.0  | Высокоуровневая реализация JSON-RPC 2.0 для Node.js с поддержкой нескольких транспортов.  | Node.js
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 Архивная копия от 4 февраля 2013 на Wayback Machine | 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
Lugate API Gateway  | 2.0 | Реализация API Gateway в виде JSON-RPC 2.0 модуля для NGINX | 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
AFJSONRPCClient | 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 Архивная копия от 21 июня 2020 на Wayback Machine | 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
sajya/server | 2.0  | JSON-RPC сервер для Laravel | PHP
JsonRpcBundle | 2.0 | JSON-RPC сервер для Symfony | 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
jsonrpc | 2.0  | Реализация клиента и сервера. Поддерживаемые протоколы взаимодействия http, ipc, websocket и tcp.  | Rust

Официальная страница[4] содержит больше реализаций Архивная копия от 17 марта 2013 на Wayback Machine. CPAN список реализаций на Perl.

## См. также

[править | править код]

* Remote procedure call (RPC);
* XML-RPC
* SOAPjr — гибрид SOAP и JSON-RPC;
* JSON-WSP — основанный на JSON-RPC протокол c спецификацией для описания сервиса.
* JSend спецификация которая только декларирует формат ответа

## Примечания

[править | править код]

1. ↑ Группы Google (неопр.). Дата обращения: 17 марта 2013. Архивировано 4 ноября 2012 года.
2. ↑ RFC 4627
3. ↑ Спецификация JSON-RPC Архивировано 17 мая 2008 года.
4. ↑ JSON-RPC — Trac (неопр.). Дата обращения: 17 марта 2013. Архивировано из оригинала 29 декабря 2014 года.

## Ссылки

[править | править код]

* Официальный сайт
* Официальная страница JSON-RPC 1.0
* JSON-RPC Google группа. Обсуждение связанных с протоколом тем
* JSON-RPC спецификации, ссылки, и пр.