JSON-RPC

• Разделы:
  • Использование
  • Примеры
  • Реализации
  • См. также
  • Примечания
  • Ссылки

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

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

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

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}

Реализации

Официальная страница[4] содержит больше реализаций. CPAN список реализаций на Perl.

См. также

• Remote procedure call (RPC);
• SOAPjr — гибрид SOAP и JSON-RPC;
• JSON-WSP — основанный на JSON-RPC протокол.

Примечания

1. ↑ Группы Google
2. ↑ RFC 4627
3. ↑ Спецификация JSON-RPC
4. ↑ JSON-RPC — Trac

С
сылки

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