JSON-RPC_2_0_Спецификация.txt

JSON-RPC_2_0_Спецификация.txt

JSON-RPC 2.0 Спецификация
Дата создания:
2010-03-26 (в зависимости от версии 2009-05-24)
Обновлено:
2013-01-04
Автор:
Рабочая группа JSON-RPC <json-rpc@googlegroups.com>

Содержание
Обзор
Соглашения
Совместимость
Объект запроса
Уведомление
Параметр структуры
Объект для ответа
Объект для ошибки
Пакет
Примеры
Расширения
1 Обзор
JSON-RPC является не сохраняющий состояния, легковесный протокол удаленного вызова процедур (RPC). В первую очередь это спецификация определяет некоторые структуры данных и правила их обработки. Это трансцендентное средство передачи, принципы которого могут использоваться одинаково поверх сокетов, протокола HTTP, или других различных сред передачи сообщений. В качестве формата данных использует JSON (RFC 4627) .

Он создан, чтобы быть простым!

2 Соглашения
Ключевые слова "ДОЛЖЕН", "НЕ ДОЛЖЕН", "ТРЕБУЕМЫЙ", "ДОЛЖНО БЫТЬ", "НЕ ДОЛЖНО БЫТЬ", "РЕКОМЕНДОВАНО", "ВОЗМОЖНО", и "НЕ ОБЯЗАТЕЛЬНО" в этом документе должны интерпретироваться, как описано в RFC 2119.

Так как JSON-RPC использует JSON, он имеет такие же типы данных (см http://www.json.org или RFC 4627). JSON может представлять четыре простых типа (строки, числа, логические и NULL) и два структурированных типа (объекты и массивы). Термин "простые" в данном описании ссылаются на любой из этих четырех простых типов JSON. Термин «структурированные" ссылается на структурированные типы JSON. Всякий раз, когда этот документ относится к любому типу JSON, первая буква всегда пишется с большой: Object, Array, String, Number, Boolean, Null. True и False также прописные.

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

Клиент определяется как источник объектов запроса и обработчик объектов ответа.
Сервер определяется как источник объектов ответа и обработчик объектов запроса.

Одно реализация этой спецификации могла бы легко исполнять обе из тех ролей, даже в одно и тоже время, другим различным клиентам или тому же самому клиенту. Эта спецификация не обращается к тому слою сложности.

3 Совместимость
Объекты запросов и ответов JSON-RPC 2.0 возможно не смогут работать с существующими JSON-RPC 1.0 клиентами или серверами. Тем не менее, легко различать две версии, элементы 2,0 всегда имеют приставку "jsonrpc" со значением "2.0" в то время как 1,0 не имеет этого. Большинство реализаций 2.0 должно попытаться обработать 1.0 объекты, даже если не равнозначны и нет намеков на аспекты класса 1.0.

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

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

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

params
Структура, имеет значения параметров, которые будут использоваться во время вызова метода. Этот элемент может быть опущен.

id
Идентификатор устанавливаемый Клиентом, который должен содержать строку, число или значение NULL, если он включен в элемент запроса. Если он не существует, предполагается, что это уведомление. Значение должно быть обычно не Null [1], цифры не должны содержат дробную часть [2]
Сервер должен ответить тем же значением в объекте ответа, если идентификатор был включен в объект запроса. Этот элемент используется для связи контекста между двумя объектами.

[1] Использование Null в качестве значения для элемента id в объект запроса вынужденная мера, потому что эта спецификация использует значение Null для ответов с неизвестной id. Кроме того, необходимо учитывать, что JSON-RPC 1.0 использует значение NULL  для идентификатора уведомления, что может привести к путанице при обработке.

[2] Дробные части могут создать проблемы, так как многие десятичные дроби не могут быть точно представлены как двоичные дроби.

4.1 Уведомление
Уведомление это объект Запроса без элемента "id" . Объект Запроса, который является уведомлением означает отсутствие интереса Клиента в получении соответствующего объекта ответа, и, таким образом объект ответа не будет возвращен клиенту. Сервер не ДОЛЖЕН отвечать на Уведомление, включая на те, которые являются в рамках пакетного запроса.

Уведомления не подтверждаемые по определению, так как у них нет объекта Ответа, который должен быть возвращен. К тому же, Клиент не должен быть оповещен ни о каких ошибках (как, например, "Недействительный параметр", "Внутренняя ошибка"

4.2 Структура параметра 
Если присутствуют параметры вызова RPC, они должны быть представлены в виде структурированного значения. Либо индексированы в массиве, либо по имени через объект.

по-индексу: Параметры должны быть массивом, содержащий значения в ожидаемом сервером порядке.
по имени: Параметры должны быть объектом, с именами членов, которые соответстветствовали бы ожидаемым сервером  именам параметров. Отсутствие ожидаемых имен может привести к генерации ошибки . Имена должны в точности совпадать именам ожидаемых параметров метода.

5 Объект Ответа
Когда вызов RPC сделан, сервер должен откликнуться с ответом, за исключением случая уведомления. Отклик выражается в виде одного объекта JSON, со следующими элементами:

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

result
Этот элемент является обязательным при успешном завершении.
Этот элемент не должен быть, если произошла ошибка при вызове метода.
Значение этого элемента определяется вызванным методом.

error
Этот элемент является обязательной в случае ошибки.
Этот член не должен быть, если не было ошибок во время вызова.
Значение этого элемента должно быть объектом, как определено в разделе 5.1.

id
Этот элемент является обязательным.
Он должна быть таким же, как значение id элемента в объекте запроса.
Если произошла ошибка при обнаружении идентификатора в объекте запроса (например, ошибка разбора / Неверный запрос), он должен быть в значении NULL.
В любом случае ДОЛЖЕН быть включен либо элемент result либо элемент error, но не должны быть включены оба элемента.

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

code
Число, указывающее тип произошедщей ошибки.
Это должно быть целое число.

message
Строка, предоставляющая краткое описание ошибки.
Сообщение должно быть ограничено краткое одно предложение.

data
Простое или Структурированное значение, содержащее дополнительную информацию об ошибке.
Это может быть опущенно.

Значение этого элемента определяется на Сервере (например, подробные сведения об ошибке, вложенные ошибки и т.д.).
Коды ошибок от -32768 до -32000 зарезервированы для предопределенных ошибок. Любой код в пределах этого диапазона, который не определен явно ниже, зарезервирован для будущего использования. Коды ошибок почти такие же, как те, что предлагаются для XML-RPC по адресу: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

Смысл кодов сообщение 
-32700 Ошибка разбора - Неверный JSON. Произошла ошибка на сервере во время разбора текста JSON.
-32600 Неверный запрос JSON - отправлен не допустимый объект запроса.
-32601 Метод не найден - метод не существует или не доступен.
-32602 Неверные Параметры - Неверный параметры метода.
-32603 Внутренняя ошибка - Внутренняя JSON-RPC ошибка.
 От -32000 до -32099  ошибка сервера Зарезервировано для реализации определенных ошибок сервера.
Остальная часть промежутка кодов доступна для применения в приложении для определения ошибок.

6 Пакет
Для отправки нескольких объектов запроса, за один раз, клиент может отправить массив заполненный объектами запросов.

После того как все объекты массива были обработаны, Сервер должен ответить массивом ответов, содержащий соответствующие объекты отклика. Объекты ответа, должны соответствовать каждому объекту запроса, за исключением каких-либо объектов уведомлений, на которые не требутся ответа. Сервер может обрабатывать пакетный RPC вызов в виде набора параллельных задач, обработывать их в любом порядке и с любой шириной параллелизма.

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

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

7 Примеры
Синтаксис:

-> Данные, отправленные на сервер
<- Данные, передаваемые Клиенту

RPC вызов с индексными параметрами:

--> {"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}

RPC вызов с именованными параметрами:

--> {"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"}

RPC вызов несуществующего метода:

--> {"jsonrpc": "2.0", "method": "foobar", "id": "1"}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "1"}

RPC вызов с недопустимым JSON:

--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

RPC вызов с недопустимым объекта запроса:

--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

Пакетный RPC вызов с недействительным JSON:

--> [
  {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
  {"jsonrpc": "2.0", "method"
]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

RPC вызов с пустой массив:
--> []
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

Не верный RPC вызов (но не пустой):
--> [1]
<-- [
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}
]

Недопустимы пакетный RPC вызов :

-> [1,2,3]
<-- [
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}
]

Пакетный RPC вызов :

--> [
        {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
        {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
        {"foo": "boo"},
        {"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},
        {"jsonrpc": "2.0", "method": "get_data", "id": "9"} 
    ]
<-- [
        {"jsonrpc": "2.0", "result": 7, "id": "1"},
        {"jsonrpc": "2.0", "result": 19, "id": "2"},
        {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
        {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "5"},
        {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
    ]

Пакетный RPC вызов (все уведомления):

--> [
        {"jsonrpc": "2.0", "method": "notify_sum", "params": [1,2,4]},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]}
    ]
<- // Ничего не возвращается для всего пакета уведомлений

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

Copyright (C) 2007-2010 по JSON-RPC Рабочей группы