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 + 1.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
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 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.

См. также[править | править вики-текст]

Примечания[править | править вики-текст]

Ссылки[править | править вики-текст]