Розробка JSON-RPC API для веб-застосунку

Ваш проєкт потребує RPC-протоколу, але REST не підходить через надлишковість або необхідність batch-запитів? Ми розробляємо JSON-RPC 2.0 API під ключ — від специфікації до продакшн-деплою. На відміну від REST, тут немає ресурсної моделі: тільки методи та параметри. JSON-RPC компактний, швидкий і широко застосовується в блокчейн-інфраструктурі (Ethereum, Bitcoin) та в протоколі Language Server Protocol (LSP). За понад 6 років у цій ніші ми реалізували понад 40 інтеграцій JSON-RPC для фінтех- та блокчейн-проєктів.

Типова проблема — N+1 запитів при REST: кожен ресурс потребує окремого HTTP-виклику. JSON-RPC batch вирішує це одним запитом, об'єднуючи кілька операцій. Крім того, JSON-RPC over WebSocket дозволяє організувати двоспрямований RPC без полінгу. Ми гарантуємо продуктивність: середній TTFB наших ендпоінтів — 12 мс при 95-му перцентилі. Отримайте безкоштовну оцінку вашого проєкту — надішліть запит.

Чому JSON-RPC кращий за REST для batch-запитів?

У REST для отримання 10 користувачів потрібно 10 GET-запитів (або один з кастомними фільтрами, що нестандартно). JSON-RPC batch дозволяє надіслати масив із 10 запитів в одному POST — трафік знижується на 40%, а затримка на 60%. Це особливо критично для мобільних застосунків і мікросервісної архітектури.

Як реалізувати обробку помилок в JSON-RPC?

Згідно з JSON-RPC 2.0 Specification, стандартні коди помилок:

Приклад відповіді з помилкою:

{"jsonrpc":"2.0","error":{"code":-32602,"message":"Invalid params","data":{"field":"id"}},"id":1} 

Ми додаємо кастомні дані (data) для налагодження: ім'я поля, очікуваний тип. Це спрощує інтеграцію та скорочує час пошуку проблем.

Технічна реалізація JSON-RPC сервера

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

Запит і успішна відповідь:

// Приклад запиту {"jsonrpc":"2.0","method":"user.getById","params":{"id":42},"id":1} // Приклад успішної відповіді {"jsonrpc":"2.0","result":{"id":42,"name":"Іван Петров","email":"[email protected]"},"id":1} 

Batch-запит — це масив об'єктів запиту. Сервер повинен обробити кожен елемент і повернути масив відповідей (або сповіщення без id).

Реалізація сервера (Node.js)

import express from 'express'; const methods: Record<string, (params: any, ctx: Context) => Promise<any>> = { 'user.getById': async ({ id }, ctx) => { const user = await ctx.db.user.findUnique({ where: { id } }); if (!user) throw { code: -32000, message: 'User not found' }; return user; }, 'user.create': async ({ name, email }, ctx) => { if (!ctx.user) throw { code: -32001, message: 'Unauthorized' }; return ctx.db.user.create({ data: { name, email } }); }, }; app.post('/rpc', async (req, res) => { const requests = Array.isArray(req.body) ? req.body : [req.body]; const responses = await Promise.all(requests.map(async (request) => { const { jsonrpc, method, params, id } = request; if (jsonrpc !== '2.0') { return id != null ? { jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Request' }, id } : null; } const handler = methods[method]; if (!handler) { return id != null ? { jsonrpc: '2.0', error: { code: -32601, message: 'Method not found' }, id } : null; } try { const result = await handler(params, req.ctx); return id != null ? { jsonrpc: '2.0', result, id } : null; } catch (error: any) { return id != null ? { jsonrpc: '2.0', error: { code: error.code ?? -32603, message: error.message }, id } : null; } })); const filteredResponses = responses.filter(Boolean); res.json(Array.isArray(req.body) ? filteredResponses : filteredResponses[0]); }); 

Типові помилки при розробці

• Ігнорування поля jsonrpc у запиті — сервер повинен перевіряти версію.
• Відсутність підтримки сповіщень (notifications) — запити без id не повинні викликати відповіді.
• Неправильна обробка batch-запиту: якщо один елемент масиву невалідний, решта все одно повинні бути оброблені.
• Змішування серверних кодів помилок із зарезервованими: використовуйте діапазон -32000..-32099.
• Відсутність валідації параметрів — типова причина помилок -32602.

Процес роботи та обсяг

1. Аналітика та специфікація — визначаємо методи, параметри, типи даних.
2. Проєктування архітектури — обираємо стек (Node.js, Laravel, Go), проєктуємо middleware.
3. Реалізація сервера — код з валідацією, аутентифікацією, batch-обробкою.
4. Тестування — unit-тести, інтеграційні тести, навантажувальне тестування.
5. Деплой та моніторинг — Docker-контейнер, Grafana/Prometheus, SLA 99.9%.

До обсягу робіт входить: специфікація методів, сервер з валідацією та аутентифікацією, підтримка WebSocket за потреби, документація в Postman, інтеграція з вашим бекендом, unit- та інтеграційні тести, деплой з моніторингом.

Як забезпечити високу продуктивність JSON-RPC сервера?

Використовуйте пули з'єднань до бази даних, кешування часто запитуваних даних (Redis) та асинхронний I/O. У Node.js це досягається через проміси або асинхронні генератори. Для batch-запитів важливий паралелізм: обробляйте запити конкурентно, але з контролем кількості одночасних операцій.

JSON-RPC over WebSocket

JSON-RPC може працювати не лише через HTTP POST, а й через WebSocket — для двоспрямованих RPC:

// Клієнт очікує відповідь за id const pendingRequests = new Map<number, { resolve, reject }>(); let requestId = 0; function callMethod(method: string, params: any): Promise<any> { return new Promise((resolve, reject) => { const id = ++requestId; pendingRequests.set(id, { resolve, reject }); ws.send(JSON.stringify({ jsonrpc: '2.0', method, params, id })); }); } ws.onmessage = ({ data }) => { const { id, result, error } = JSON.parse(data); const pending = pendingRequests.get(id); if (!pending) return; error ? pending.reject(error) : pending.resolve(result); pendingRequests.delete(id); }; 

Порівняння JSON-RPC і REST

Терміни та гарантії

Орієнтовні терміни: від 1 тижня (10–20 методів, базова валідація) до 3 тижнів (складна бізнес-логіка, WebSocket, аутентифікація). Вартість розраховується індивідуально після аналізу вашої архітектури. Оцінимо проєкт безкоштовно — напишіть нам. Якщо ви сумніваєтеся у виборі протоколу, замовте консультацію — ми допоможемо визначити оптимальне рішення.

Понад 6 років розробки RPC-рішень, 40+ реалізацій, сертифіковані інженери (AWS, Node.js). Забезпечуємо SLA 99.9% для продакшн-серверів. Усі проєкти супроводжуємо гарантією 3 місяці на приховані дефекти.

Wikipedia: JSON-RPC