JSON-RPC

JSON-RPC (сокр. от англ. JavaScript Object Notation 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
}

Версия 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": 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}

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

--> [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++
Phobos2.0Реализация для Qt/C++. Абстрагирует уровень передачи данных (готовые к использованию классы для TCP и HTTP).C++
qjsonrpc2.0Реализация для Qt/C++. Поддерживает соединения между сообщениями и QObject слотами (как QDBus, qxtrpc). Использует новые JSON классы, включённые в Qt 5.C++
JSON Toolkit Архивная копия от 13 января 2013 на Wayback Machine2.0Реализация на Delphi (переименован в SuperObject)Delphi
SuperObject2.0Реализация на Delphi (поддержка прекращена 14.12.2018)Delphi
pascal-jsonrpc-lite 2.0 Реализация на Pascal (Lazarus, Delphi) Pascal
go/net/rpc1.0Реализация JSON-RPC стандартной библиотеки GoGo
jsonrpc4j2.0Java реализация JSON-RPC 2.0 поддерживает как сокеты, так и HTTP-соединение.Java
json-rpc1.0Базовая Java/JavaScript реализация, которая хорошо интегрируется в Android/Servlets/Standalone Java/JavaScript/App-Engine приложения.Java / JavaScript
jpoxy (недоступная ссылка)2.0Простая Java реализация JSON-RPC созданная для упрощения реализации доступа к POJOs через сырой RPC фрэймворк.Java
JSON Service2.0JSON-RPC серверная реализация с поддержкой Service Mapping Description. Хорошо интегрируется с Dojo Toolkit и Spring Framework.Java
JSON-RPC 2.02.0Лёгкая библиотека на Java для разбора и сериализации JSON-RPC 2.0 сообщений (open source). Несколько реализация на сайте. (Base, Client, Shell, …)Java
java-json-rpc2.0Реализация для J2EE серверов.Java
lib-json-rpc2.0Реализация servlet, client, JavaScriptJava
simplejsonrpc2.0Простой JSON-RPC 2.0 Servlet, обслуживающий методы класса.Java
gson-rmi2.0Легковесный, независимый от способа передачи RMI фрэймворк разработанный для распределённых вычислений.Java
THETA-RPC 2.0 Высокоуровневая реализация JSON-RPC 2.0 для Node.js с поддержкой нескольких транспортов. Node.js
jsonrpcjs2.0JavaScript клиентская библиотека для JSON-RPC 2.0, Не имеет зависимостей.JavaScript
easyXDM2.0Библиотека для cross-domain соединений с поддержкой RPC. Поддерживает все браузеры postMessage, nix, frameElement, window.name, и FIM, очень проста в использовании.JavaScript
Dojo Toolkit1.0+Предоставляет поддержку JSON-RPCJavaScript
Pmrpc2.0JavaScript библиотека для использования в HTML5 браузерах. Реализация JSON-RPC, используя HTML5 postMessage API для передачи сообщений.JavaScript
qooxdoo Архивная копия от 4 февраля 2013 на Wayback Machine2.0Имеет JSON-RPC реализацию с опциональными бэк-эндами на Java, PHP, Perl и Python.JavaScript, Java, PHP, PERL, & Python
JSON-RPC Реализация на JavaScript2.0Поддерживает JSON-RPC через HTTP и TCP/IP.JavaScript
jabsorb2.0Легковесный Ajax/Web 2.0 JSON-RPC Java фреймворк, расширяющий протокол JSON-RPC дополнительной ORB функциональностью, такой как поддержка циклических зависимостей.JavaScript, Java
The Wakanda platform2.0Поддерживает JSON-RPC 2.0 клиент внутри Ajax Framework и JSON-RPC 2.0 сервис в серверном JavaScriptJavaScript
Deimos1.0+2.0Серверная реализация для Node.js/JavaScript.JavaScript
Barracuda Web Server2.0Barracuda Web Server’s интегрированныйLua
Lugate API Gateway 2.0Реализация API Gateway в виде JSON-RPC 2.0 модуля для NGINXLua
DeferredKit1.0Поддерживает JSON-RPC 1.0 клиент.Objective-C
Demiurgic2.0JSON-RPC 2.0 клиент для Objective-CObjective-C
Oxen iPhone Commons JSON components1.0JSON-RPC 1.0 клиент для Objective-CObjective-C
objc-JSONRpc2.0Objective-c JSON RPC клиент. Поддерживает уведомления, простые вызовы и множественные вызовы.Objective-C
AFJSONRPCClient2.0Objective-c JSON RPC клиент.Objective-C
JSON::RPC2.0Реализация сервера JSON RPC 2.0Perl
json-rpc-perl62.0Клиент и сервер.Perl 6
php-json-rpc Архивная копия от 21 июня 2020 на Wayback Machine2.0Простая PHP реализация JSON-RPC 2.0 через HTTP клиента.PHP
JQuery JSON-RPC Server2.0JSON-RPC сервер, специально сделанный для работы с Zend Framework JSON RPC Server.PHP, JavaScript
jsonrpc2php2.0PHP5 JSON-RPC 2.0 базовый класс и пример сервераPHP
tivoka1.0 + 2.0Универсальный клиент/серверная JSON-RPC библиотека для PHP 5+.PHP
junior2.0Client/server библиотека для JSON-RPC 2.0PHP
json-rpc-php2.0Client/server библиотека для JSON-RPC 2.0PHP
JSONRpc22.0Реализация с «dot magic» для PHP (= поддержка группировки методов и разделения точками)PHP
GetResponse jsonRPCClient2.0Объектно-ориентированная реализация клиентаPHP
zoServices2.0PHP, Node.js и JavaScript реализация JSON-RPC 2.0PHP, JavaScript, Node.js
json-rpc2php2.0Серверная и клиентская реализация для PHP. Содержит JavaScript клиент, использующий jQueryPHP, JavaScript
jsonrpc-php2.0JSON-RPC реализация для PHPPHP
php-json-rpc2.0Реализация JSON-RPC 2.0.PHP
sajya/server 2.0 JSON-RPC сервер для Laravel PHP
JsonRpcBundle2.0JSON-RPC сервер для SymfonyPHP
Django JSON-RPC 2.02.0JSON-RPC сервер для DjangoPython
PyjamasJSON-RPC клиентская реализация.Python
Zope 31.1JSON RPC реализация для Zope 3Python
jsonrpclib2.0JSON-RPC клиентский модуль для Python.Python
tornadorpc2.0Поддерживает JSON-RPC требует Tornado web server.Python
tinyrpc2.0Поддерживает JSON-RPC через TCP, WSGI, ZeroMQ и др. Разделяет передачу данных от обработки сообщений, может работать без пересылки сообщений.Python
jsonrpc2.0JSON-RPC 2.0 для Python + Twisted.Python
bjsonrpc1.0+Реализация через TCP/IP (асинхронная, двунаправленная)Python
Barrister RPC2.0JSON-RPC реализация клиента и сервераPython, Ruby, JavaScript (Node.js + web browser), PHP, Java
pyramid_rpc2.0Гибкая JSON-RPC реализация интегрированная в Pyramid web application. Работает с Pyramid’s системой авторизации.Python
rjr2.0JSON-RPC через TCP/UDP, HTTP, WebSockets, AMQP, и прочие.Ruby (EventMachine) сервер с Ruby и JavaScript клиентами.
jimson2.0Клиент и сервер для RubyRuby
JSON-RPC Objects1.0+Реализация только объектов (без клиента и сервера).Ruby
JSON-RPC RT2.0Полная поддержка JSON-RPC 2.0 через TCP.Windows Runtime (WinRT)
XINS2.0С версии 2.0, поддерживает JSON и JSON-RPC.XML
jsonrpc 2.0 Реализация клиента и сервера. Поддерживаемые протоколы взаимодействия http, ipc, websocket и tcp. Rust

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

См. также

Примечания

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

Ссылки

This article is issued from Wikipedia. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.