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

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

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

JSON-RPC работает, отсылая запросы к серверу, реализующему протокол. Клиентом обычно является программа, которой нужно вызвать метод на удалённой системе. Множество входных параметров может быть передано удалённому методу как массив или запись. Метод также может вернуть множество выходных данных (это зависит от реализации). Удалённый метод вызывается отправлением запроса на удалённый сервер посредством HTTP или TCP/IP - сокета (начиная с версии 2.0). При использовании HTTP заголовок Content-Type определяется как application/json .

Все передаваемые данные — простые записи , сериализованные в JSON . Запрос — вызов определённого метода, предоставляемого удалённой системой. Он должен содержать три обязательных свойства:

• 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": 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} 

Реализации

Официальная страница содержит от 17 марта 2013 на Wayback Machine . CPAN список .

См. также

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

Примечания

Ссылки

• . Обсуждение связанных с протоколом тем