JSON-RPC

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

История

Протокол JSON-RPC был разработан как альтернатива более сложным и тяжёлым протоколам, таким как SOAP (Simple Object Access Protocol) и XML-RPC, которые используют XML для сериализации данных. Основной целью создания JSON-RPC было упрощение взаимодействия между веб-сервисами, особенно в контексте веб-приложений, где важна скорость и малый размер передаваемых данных.

Первая версия протокола, JSON-RPC 1.0, была предложена в 2005 году. Она определяла базовые правила для вызова процедур и передачи параметров, но не имела строгой спецификации для обработки ошибок и версионирования. В 2010 году была опубликована спецификация JSON-RPC 2.0, которая стала более широко распространённой и стандартизированной. Версия 2.0 добавила чёткую структуру для объектов запроса и ответа, ввела понятие идентификатора запроса (id) для сопоставления запросов и ответов, а также определила стандартный формат для сообщений об ошибках.

Принцип работы

JSON-RPC работает по модели «запрос-ответ». Клиент отправляет серверу JSON-объект, содержащий информацию о вызываемой процедуре и её параметрах. Сервер обрабатывает запрос, выполняет соответствующую процедуру и возвращает ответ в виде JSON-объекта, содержащего результат выполнения или информацию об ошибке. Протокол не зависит от транспортного уровня и может использоваться поверх HTTP, WebSockets, TCP, UDP или других протоколов.

Формат запроса

Согласно спецификации JSON-RPC 2.0, запрос представляет собой JSON-объект со следующими обязательными полями:

• jsonrpc — строка, указывающая версию протокола (должна быть «2.0»).
• method — строка, содержащая имя вызываемой процедуры.
• params — значение, передаваемое в качестве параметров процедуры. Может быть структурой (массивом или объектом) или отсутствовать, если процедура не требует параметров.
• id — уникальный идентификатор запроса, используемый для сопоставления запроса с ответом. Может быть числом, строкой или null. Если id отсутствует или равен null, запрос считается уведомлением (notification), на которое сервер не отправляет ответ.

Пример запроса:

``json { "jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1 } ``

Формат ответа

Ответ представляет собой JSON-объект со следующими полями:

• jsonrpc — строка «2.0».
• result — результат выполнения процедуры. Это поле присутствует только в случае успешного выполнения.
• error — объект с информацией об ошибке, если выполнение процедуры завершилось неудачей. Поля error: code (числовой код ошибки), message (строка с описанием ошибки) и data (необязательное значение с дополнительной информацией).
• id — идентификатор запроса, на который был дан ответ. Если запрос был уведомлением, id не указывается.

Пример успешного ответа:

``json { "jsonrpc": "2.0", "result": 19, "id": 1 } ``

Пример ответа с ошибкой:

``json { "jsonrpc": "2.0", "error": { "code": -32601, "message": "Method not found" }, "id": 1 } ``

Уведомления

Уведомление — это запрос, для которого не требуется ответа. В таком запросе поле id отсутствует или равно null. Сервер не отправляет ответ на уведомление, даже если выполнение процедуры завершилось ошибкой. Уведомления используются для односторонней передачи данных, например, для отправки событий или логов.

Коды ошибок

Спецификация JSON-RPC 2.0 определяет стандартные коды ошибок, которые могут быть возвращены сервером:

• -32700 — Parse error (ошибка разбора JSON).
• -32600 — Invalid Request (неверный формат запроса).
• -32601 — Method not found (метод не найден).
• -32602 — Invalid params (неверные параметры).
• -32603 — Internal error (внутренняя ошибка сервера).
• -32000..-32099 — Server error (зарезервировано для ошибок, специфичных для реализации).

Кроме того, сервер может определять собственные коды ошибок, выходящие за пределы этого диапазона.

Применение

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

• Веб-сервисы и API — JSON-RPC часто используется для создания REST-подобных API, особенно в системах, где важна производительность и простота. Например, многие криптовалютные кошельки и блокчейн-платформы (например, Bitcoin, Ethereum) предоставляют JSON-RPC API для взаимодействия с узлами сети.
• Микросервисная архитектура — в микросервисных системах JSON-RPC может использоваться для вызова процедур между сервисами, обеспечивая лёгкую интеграцию и низкую задержку.
• Встроенные системы и IoT — благодаря малому размеру JSON-сообщений и простоте реализации, JSON-RPC подходит для устройств с ограниченными ресурсами, таких как датчики, контроллеры и микроконтроллеры.
• Инструменты разработки — JSON-RPC используется в различных инструментах для отладки и управления, например, в протоколе Debug Adapter Protocol (DAP) и Language Server Protocol (LSP), которые применяются в средах разработки (IDE).

Сравнение с другими протоколами

JSON-RPC часто сравнивают с другими протоколами удалённого вызова процедур:

• XML-RPC — использует XML для сериализации данных, что делает сообщения более объёмными и сложными для разбора. JSON-RPC проще и быстрее.
• SOAP — более сложный и многофункциональный протокол, поддерживающий расширенные возможности, такие как безопасность и транзакции. JSON-RPC ориентирован на простоту и минимализм.
• gRPC — использует Protocol Buffers для сериализации и HTTP/2 для транспорта, обеспечивая высокую производительность и поддержку потоковой передачи. JSON-RPC проще в реализации, но менее производителен.
• REST — архитектурный стиль, а не протокол. REST использует HTTP-методы (GET, POST, PUT, DELETE) для работы с ресурсами, в то время как JSON-RPC фокусируется на вызове процедур. JSON-RPC может быть более удобным для систем, где требуется выполнение команд, а не управление ресурсами.

Реализации

JSON-RPC реализован на множестве языков программирования, включая Python, JavaScript, Java, C++, Go, Ruby, PHP и другие. Существуют как готовые библиотеки, так и фреймворки, упрощающие интеграцию протокола в приложения. Примеры популярных библиотек:

• Python — jsonrpclib, python-jsonrpc, aiohttp-json-rpc (для асинхронных приложений).
• JavaScript — jayson, json-rpc2, ws-json-rpc (для WebSockets).
• Java — jsonrpc4j, Apache XML-RPC (с поддержкой JSON).
• Go — gorilla/rpc, jsonrpc2.

Критика

Несмотря на простоту и популярность, JSON-RPC имеет некоторые недостатки. Основные из них:

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

Интересные факты

• JSON-RPC 2.0 является основой для протокола Language Server Protocol (LSP), который используется в редакторах кода для предоставления функций автодополнения, проверки синтаксиса и рефакторинга.
• В блокчейн-сетях, таких как Bitcoin и Ethereum, JSON-RPC является стандартным способом взаимодействия с узлами для выполнения транзакций, получения баланса и управления смарт-контрактами.
• Протокол JSON-RPC может быть использован в сочетании с WebSockets для создания двустороннего канала связи, что позволяет серверу отправлять уведомления клиенту без необходимости постоянного опроса.

Источники

• Спецификация JSON-RPC 2.0 (официальный документ)
• Документация Bitcoin Core по JSON-RPC API
• Документация Ethereum по JSON-RPC API
• Статья «JSON-RPC: A Lightweight Remote Procedure Call Protocol» на сайте JSON-RPC.org