JSON-RPC – это простой протокол для создания API в стиле RPC (Remote Procedure Call).
RPC означает Remote Procedure Call, то есть, на бэкенд посылается команда о выполнении некоего кода. Команда по смыслу и предназначению может быть любой.
Все запросы отправляются только в один эндпоинт. Для отправки запросов в качестве транспорта может использоваться что угодно, но как правило, используется протокол HTTP, а точнее, лишь только один его метод – POST.
Как вы поняли из названия, все сообщения представляются в формате JSON. В отличие от REST, JSON-RPC вводит требования к составу запросов и ответов – они должны включать обязательные элементы.
➡️ Запросы могут содержать следующие свойства:
1. jsonrpc — версия JSON-RPC (актуальная 2.0)
2. method – строка с именем вызываемого метода
3. params – массив данных, передаваемых на сервер
4. id – значение любого типа, которое используется для установки соответствия между запросом и ответом.
⬅️ Ответы сервера должны содержать следующие элементы:
1. jsonrpc — версия JSON-RPC (актуальная 2.0)
2. result – данные в случае успеха; error — код ошибки, если произошла ошибка
3. id – то же значение, что и в запросе, к которому относится данный ответ
Примеры запросов и ответов
Запрос
{"jsonrpc": "2.0", "method": "post.like", "params": {"post": "12345"}, "id": 1}
Успешный ответ{"jsonrpc": "2.0", "result": {"likes": 123}, "id": 1}
Ответ с ошибкой{"jsonrpc": "2.0", "error": {"code": 666, "message": "Post not found"}, "id": "1"}
Таким образом, JSON-RPC более формализован, чем REST. Потенциально это может уменьшить количество разногласий и разночтений в команде, однако обратная сторона формализации – снижение гибкости.✅ Ещё пара фишек JSON-RPC
1. Запросы можно группировать в пакеты, подобно gRPC.
2. Можно отправлять запросы-уведомления, не требующие ответа от сервера (в таком случае не передаётся id в запросе).
🚧 Ограничения JSON-RPC
➖ Сложность кэширования. RPC не поддерживает использование инфраструктурного кэширования (например, CDN), так как использует только метод POST, который не является идемпотентным, то есть многократное повторение одних и тех же запросов POST может возвращать разные результаты.
➖ Сложность балансировки нагрузки. Балансировка нагрузки в JSON-RPC не так проста и эффективна, как в REST, который предлагает разные HTTP-методы, коды ответов и заголовки для управления балансировкой нагрузки
В случае возникновения ошибок на одной из нод, JSON-RPC не может перенаправить запрос на другую ноду, в отличие от REST, который использует коды ответов HTTP и заголовки для управления балансировкой нагрузки.
➖ Снижение уровня абстракции. Парадигма RPC требует от клиента большей погружённости и связанности с уровнем реализации, чем REST. Клиент должен знать, какие процедуры вызывать на сервере, какие параметры передавать и какой формат ответа ожидать. REST имеет выше уровень абстракции, чем JSON-RPC, потому что он отделяет ресурсы в системе от способа доступа к ним. Клиенту не нужно знать, как сервер реализует свою логику, а достаточно знать, какие ресурсы доступны, какие HTTP-методы применимы к ним и какой формат данных используется.
➖ Нет поддержки кодов состояний HTTP.
Когда лучше использовать JSON-RPC вместо REST
Как обычно: нет лучшего рецепта и всё зависит от ситуации.
JSON-RPC может оказаться эффективнее, когда:
1️⃣ Требуются сложные вычисления (HTTP-глаголов недостаточно), затрагивающие множество действий и объектов.
2️⃣ Предметная область специфична и не поддаётся адекватному разбиению на ресурсы, а всё взаимодействие заключается в запуске удалённых процедур.
3️⃣ Требуется работать над другими каналами передачи данных, кроме HTTP, или поддерживать открытое соединение (например, через WebSockets).
📎 Материалы
1. REST? Возьмите тупой JSON-RPC
2. Статьи от разработчика-адепта JSON-RPC: часть 1, часть 2
3. JSON-RPC? Возьмите хитрый REST — критика JSON-RPC
4. Обзорная статья от Merion Academy
5. Видео JSON-RPC или когда REST неудобен
#api #интеграции
