JSON-RPC

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

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

Версия	Описание	Дата
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 спецификация которая только декларирует формат ответа

Примечания

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

Ссылки

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

[1] Группы Google (неопр.). Дата обращения: 17 марта 2013. Архивировано 4 ноября 2012 года.

[2] RFC 4627

[3] Спецификация JSON-RPC Архивировано 17 мая 2008 года.

[4] JSON-RPC — Trac (неопр.). Дата обращения: 17 марта 2013. Архивировано из оригинала 29 декабря 2014 года.

[1]

[2]

[3]

[4]

JSON-RPC

Содержание

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

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

Примеры

Версия 1.0

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

Версия 2.0

Реализации

См. также

Примечания

Ссылки

Навигация

JSON-RPC

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

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

Примеры

Версия 1.0

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

Версия 2.0

Реализации

См. также

Примечания

Ссылки

Навигация

Поиск