JSON-RPC

Материал из BitcoinWiki
Это утверждённая версия страницы. Она же — наиболее свежая версия.
Перейти к: навигация, поиск
JSON-RPC

JSON-RPC – протокол удаленного вызова процедур, который использует JSON (RFC 4627) в качестве формата данных. Данный протокол во многом похож на XML-RPC, спецификация определяет несколько типов данных и правила их обработки. JSON-RPC поддерживает уведомления и множественные вызовы, так как информация, приходящая на сервер не требует ответа. Он разработан, чтобы быть простым!

История[править]

Первая версия протокола была представлена в 2005 году и по настоящий момент является официальной. В 2007 году вышло первое дополнение 1.1 WD, где были добавлены специфичные параметры, именованные коды ошибок и функции самонаблюдения. После были выпущены альтернативные соглашения 1.1 Alt и 1.1 Object Specification, также в 2007 году была выпущена версия 1.2, которая в дальнейшем была переименована в 2.0, добавлены именованные параметры и очередь вызовов. Последнее обновление было представлено в 2013 году.

Использование[править]

JSON-RPC производит отсылку запросов к серверу, реализующему удаленный протокол. Как клиент в большинстве случаев выступает программа, которой необходимо вызвать метод на удаленной системе. Входные параметры передаются в качестве массива или объекта, в некоторых случаях возможна передача выходных данных. Процесс осуществляется посредством отправки запроса на удаленный сервер через http или tcp/ip сокет. В случае http заголовок Content-Type определяется как application/json.

JSON RPC for Bitcoin

Особенности[править]

  1. Стандартна и имеет большое количество библиотек для разных платформ.
  2. Простой парсинг, лучше аналога XML-RPC
  3. Обработка ошибок является встроенной функцией
  4. Поддерживается очередь вызовов
  5. Единая точка для API.
  6. Поддерживаются оригинальные параметры при вызове методов.

JSON-RPC 2.0[править]

Условные обозначения[править]

Ключевые обозначения "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" следует интерпретировать как в RFC 2119.

Поскольку JSON-RPC базируется на JSON, ему свойственен тот же тип системы (RFC 4627 ). В JSON могут быть реализованы четыре простых типа (string, Numbers, Booleans, и Null) и два структурированных типа (Objects и Arrays). Термин «Primitive» в этом описании ссылается на любой из этих четырех примитивных типов JSON. Термин «Structured» ссылается на структурированные типы JSON. В каждом случае, относящемуся к любому типу JSON, первая буква всегда будет заглавная: Object, Array, String, Number, Boolean, Null. True и False также всегда указываются с заглавной.

Все имена, передаваемые между Клиентом и Сервером, для любого типа данных, должны рассматриваться как чувствительные к регистру. Функцию терминов, способ и процедуру передачи могут считаться взаимозаменяемыми.

Клиент определяется как источник объектов Request и обработчик объектов Response. Сервер определяется как источник объектов Response и обработчик объектов Request. Одна из реализаций этой спецификации может легко выполнить обе эти роли, даже в случае одного или нескольких клиентов. Данная спецификация не учитывает уровень сложности.

Совместимость[править]

Объекты запроса JSON-RPC 2.0 и объекты Response могут не работать с существующими клиентами или серверами JSON-RPC 1.0. Тем не менее, легко отличить две версии, так как 2.0 всегда имеет элемент с именем «jsonrpc» со значением String «2.0», а 1.0 - нет. В большинстве реализаций 2.0 можно рассмотреть вопрос о том, чтобы попытаться обработать объекты 1.0, даже если они не относятся к одноранговым и классовым аспектам 1.0.

Объект запроса[править]

Вызов RPC представляется путем отправки объекта Request на сервер. Объект Request имеет следующие элементы:

jsonrpc Строка, указывающая версию протокола JSON-RPC должна быть записана в точности как «2.0».

method Строка, содержащая имя метода, который необходимо вызвать. Имена методов, начинающиеся со слова rpc, за которым следует символ периода (U + 002E или ASCII 46), зарезервированы для rpc-внутренних методов и расширений и НЕ ДОЛЖНЫ использоваться ни для чего другого.

Params Структурированная переменная, содержащая значения параметров, которые будут использоваться во время вызова метода. Такой элемент МОЖЕТ быть опущен.

id Идентификатор, установленный Клиентом, который ДОЛЖЕН содержать значение String, Number или Null, если включен. Если он не включен, предполагается, что это уведомление. Значение ДОЛЖНО, как правило, не быть нулевым, а числа НЕ ДОЛЖНЫ содержать дробные части.

Сервер ДОЛЖЕН отвечать с тем же значением в объекте Response, если он включен. Этот элемент используется для корреляции контекста между двумя объектами. Использование Null в качестве значения для элемента id в объекте Request не рекомендуется, поскольку эта спецификация использует значение Null для ответов с неизвестным идентификатором. Помимо этого, поскольку JSON-RPC 1.0 использует значение id для Null для уведомлений, это может вызвать путаницу при обработке.

Использование дробных чисел может быть проблематичным, так как многие десятичные дроби не могут быть точно представлены как двоичные.

Уведомление[править]

Уведомление - это объект запроса без элемента «id». Объект Request, являющийся уведомлением, означает отсутствие интереса Клиента к соответствующему объекту Response, в этом случае объект ответа не должен быть возвращен клиенту. Сервер НЕ ДОЛЖЕН отвечать на уведомление, включая те, которые входят в пакетный запрос. Уведомления не могут быть подтверждены по определению, поскольку они не имеют возвращаемого объекта Response. Таким образом, Клиент не будет знать о каких-либо ошибках (например, «Недопустимые параметры», «Внутренняя ошибка»).

Структуры параметров[править]

Если они присутствуют, параметры для вызова RPC ДОЛЖНЫ быть представлены как структурированные переменные. По позиции через массив либо по имени через объект. по позиции: params ДОЛЖНЫ быть массивом, содержащим значения в ожидаемом порядке сервера. по имени: params ДОЛЖЕН быть объектом, с именами участников, которые соответствуют именам ожидаемых параметров сервера. Отсутствие ожидаемых имен МОЖЕТ привести к генерированию ошибки. Имена ДОЛЖНЫ точно совпадать, включая случай, с ожидаемыми параметрами метода.

Объект ответа[править]

Когда выполняется вызов RPC, сервер ДОЛЖЕН отвечать как Response, за исключением случаев уведомлений. Ответ выражается как один объект JSON со следующими членами:

jsonrpc Строка, указывающая версию протокола JSON-RPC должна быть записана точно как «2.0».

result Этот элемент НЕОБХОДИМ для успеха. Этот элемент НЕ ДОЛЖЕН существовать, если возникла ошибка при вызове метода. Значение этого элемента определяется методом, вызываемым на сервере.

error Этот элемент НЕОБХОДИМ при ошибке. Этот член НЕ ДОЛЖЕН существовать , если во время вызова никаких ошибок не было. Значение этого элемента должно быть объектом , как определено в разделе 5.1.

id Этот элемент НЕОБХОДИМ. Он ДОЛЖЕН быть таким же, как значение элемента id в объекте Request. Если при обнаружении идентификатора в объекте Request возникла ошибка (например, ошибка Parse / Invalid Request), она ДОЛЖНА быть Null. Любой элемент результата или элемент ошибки ДОЛЖЕН быть включен, но одновременно оба члена НЕ ДОЛЖНЫ быть включены.

Объект ошибки[править]

Когда вызов RPC встречает ошибку, объект ответа ДОЛЖЕН содержать элемент ошибки со значением, являющимся объектом со следующими элементами:

code Номер, указывающий тип ошибки, который произошел. Номер ДОЛЖЕН быть целым числом.

message Строка, содержащая краткое описание ошибки. Сообщение ДОЛЖНО быть ограничено кратким единственным предложением.

data Примитивное или структурированное значение, содержащее дополнительную информацию об ошибке. Этот элемент может быть опущен. Значение этого элемента определяется сервером (например, подробная информация об ошибках, вложенные ошибки и т. Д.).

Коды ошибок от -32768 до -32000 включительно зарезервированы для предопределенных ошибок. Любой код в этом диапазоне, исключая указанные ниже, зарезервирован для будущего использования. Коды ошибок почти такие же, как и для XML-RPC.

code message meaning
-32700 Parse error Ошибка синтаксического анализа JSON, полученный сервером, не действителен. Произошла ошибка на сервере при анализе текста JSON.
-32600 Invalid Request Сообщение JSON не является допустимым объектом Request.
-32601 Method not found Метод не существует / недоступен.
-32602 Invalid params Недопустимый параметр метода.
-32603 Internal error Внутренняя ошибка JSON-RPC.
-32000 до -32099 Server error Зарезервировано для определенных сервером ошибок.

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

Batch[править]

Чтобы отправить несколько объектов Request одновременно, клиент может отправить массив, заполненный объектами Request.

Сервер должен ответить массивом, содержащим соответствующие объекты Response, после того, как все объекты запроса пакета были обработаны. Объект Response ДОЛЖЕН существовать для каждого объекта Request, за исключением тех, что НЕ ДОЛЖНЫ быть объектами Response для уведомлений. Сервер МОЖЕТ обрабатывать пакетный вызов RPC как набор одновременных задач, обрабатывая их в любом порядке и с любой шириной параллелизма.

Объекты Response, возвращаемые из пакетного вызова, могут быть возвращены в массиве в любом порядке. Клиент ДОЛЖЕН соответствовать контексту между набором объектов Request и результирующим набором объектов Response на основе элемента id в каждом объекте.

Если сам вызов пакета rpc не может быть признан допустимым JSON или как массив с хотя бы одним значением, ответ от сервера ДОЛЖЕН быть единственным объектом Response. Если в массиве Response отсутствуют объекты Response, которые должны быть отправлены клиенту, сервер НЕ ДОЛЖЕН возвращать пустой массив, в таком случае он ничего не должен возвращать.

Расширения[править]

Имена методов, начинающиеся с rpc. зарезервированы для системных расширений и НЕ ДОЛЖНЫ использоваться ни для чего другого. Каждое расширение системы определено в соответствующей спецификации. Все расширения системы являются ДОПОЛНИТЕЛЬНЫМИ.

См. также на BitcoinWiki[править]

Подробнее[править]