Спецификация JSON-RPC 2.0

1 Обзор

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

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

2 Соглашения

Ключевые слова "ДОЛЖЕН", "НЕ ДОЛЖЕН", "ТРЕБУЕТСЯ", "РЕКОМЕНДУЕТСЯ", "МОЖЕТ" и "НЕОБЯЗАТЕЛЬНО" в этом документе должны интерпретироваться как описано в RFC 2119. ("MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL").

Поскольку JSON-RPC использует JSON, он имеет систему того же типа (см. http://www.json.org или RFC 4627). JSON может представлять четыре примитивных типа (Строки, числа, логические значения и Null) и два структурированных типа (Объекты и Массивы). Термин "Примитивный" в этой спецификации ссылается на любой из этих четырех примитивных типов JSON. Термин "Структурированный" относится к любому из структурированных типов JSON. Всякий раз, когда этот документ ссылается на какой-либо тип JSON, первая буква всегда пишется с заглавной буквы: Объект, Массив, Строка, Число, Логическое значение, Null. Истина и Ложь также пишутся с заглавной буквы.

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

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

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

3 Совместимость

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

4 Объект запроса

Вызов RPD представлен отправкой объекта запроса на Сервер. Объект запроса содержит следующие элементы:

• jsonrpc - Строка, указывающая версию протокола JSON-RPC. ДОЛЖНО быть точно "2.0".
• method - Строка, содержащая имя вызываемого метода. Имена методов, начинающиеся со слова rpc, за которым следует символ точки (U+002E или ASCII 46), зарезервированы для внутренних методов и расширений rpc и НЕ ДОЛЖНЫ использоваться ни для чего другого.
• params - Структурированное значение, содержащее значения параметров, которые будут использоваться во время вызова метода. Этот элемент МОЖЕТ быть опущен.
• id - Идентификатор, установленный Клиентом, который ДОЛЖЕН содержать строку, число или NULL значение, если оно включено. Если он не включен, предполагается, что это уведомление. Значение обычно не должно быть нулевым [1], а числа НЕ ДОЛЖНЫ содержать дробных частей [2]

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

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

4.1 Уведомление

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

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

4.2 Структуры параметров

При наличии параметры для вызова RPC ДОЛЖНЫ быть предоставлены в виде структурированного значения. Либо по позиции через массив, либо по имени через объект.

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

5 Объект ответа

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

• jsonrpc - Строка, указывающая версию протокола JSON-RPC. ДОЛЖНО быть точно "2.0".
• result - 
  • Этот элемент НЕОБХОДИМ при успешном ответе.
  • Этот элемент НЕ ДОЛЖЕН существовать, если произошла ошибка при вызове метода.
  • Значение этого элемента определяется методом, вызываемым на Сервере.
• error -
  • Этот элемент ТРЕБУЕТСЯ при ошибке.
  • Этот элемент НЕ ДОЛЖЕН существовать, если во время вызова не было ошибки.
  • Значение для этого элемента ДОЛЖНО быть Объектом, как определено в разделе 5.1.
• id - 
  • Этот элемент ЯВЛЯЕТСЯ ОБЯЗАТЕЛЬНЫМ.
  • Он ДОЛЖНО совпадать со значением элемента идентификатора в объекте запроса.
  • Если произошла ошибка при определении идентификатора в объекте запроса (например, ошибка синтаксического анализа/Недопустимый запрос), он ДОЛЖЕН быть нулевым.

ДОЛЖЕН быть включен либо элемент "result", либо элемент "error", но оба элемента НЕ ДОЛЖНЫ быть включены.

5.1 Объект ошибки

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

• code
  • Число, указывающее тип возникшей ошибки.
  • Это ДОЛЖНО быть целое число.
• message
  • Строка, содержащая краткое описание ошибки.
  • Сообщение ДОЛЖНО быть ограничено кратким одним предложением.
• data
  • Примитивное или структурированное значение, содержащее дополнительную информацию об ошибке.
  • Может быть опущено.
  • Значение этого элемента определяется Сервером (например, подробная информация об ошибках, вложенные ошибки и т.д.).

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

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

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]}
    ]
<-- //Для всех пакетов уведомлений ничего не возвращается

Расширения

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

---

Авторское право (C) 2007-2010 Рабочей группой JSON-RPC

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

Ограниченные разрешения, предоставленные выше, являются бессрочными и не будут отменены.

Этот документ и содержащаяся в нем информация предоставляются "КАК ЕСТЬ", и ОТ ВСЕХ ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ОТКАЗЫВАЮТСЯ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ, ЛЮБЫМИ ГАРАНТИЯМИ ТОГО, ЧТО ИСПОЛЬЗОВАНИЕ ПРИВЕДЕННОЙ ЗДЕСЬ ИНФОРМАЦИИ НЕ НАРУШИТ НИКАКИХ ПРАВ ИЛИ КАКИХ-ЛИБО ПОДРАЗУМЕВАЕМЫХ ГАРАНТИЙ ТОВАРНОЙ ПРИГОДНОСТИ ИЛИ ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ.

---

Лого взято из Sajya {JSON-RPC} server for Laravel framework