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

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

JSON-RPC—простий протокол віддаленого виклику процедур з використанням JSON. Версія 2.0—поточний стандарт. На відміну від REST, нема концепції ресурсів—тільки методи та параметри. Популярний у блокчейн-екосистемі (Ethereum JSON-RPC, Bitcoin RPC), мовних серверах (LSP), деяких платіжних API.

Специфікація 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
}

Помилка:

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

Notification (без id—відповідь не потрібна):

{ "jsonrpc": "2.0", "method": "log.event", "params": { "type": "page_view" } }

Batch (кілька запитів в одному HTTP-запиті):

[
  { "jsonrpc": "2.0", "method": "user.get", "params": { "id": 1 }, "id": 1 },
  { "jsonrpc": "2.0", "method": "user.get", "params": { "id": 2 }, "id": 2 }
]

Коди помилок

Стандартні коди з специфікації:

Реалізація сервера (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, { db, user: req.user });
      return id != null ? { jsonrpc: '2.0', result, id } : null;
    } catch (error) {
      return id != null
        ? { jsonrpc: '2.0', error: { code: error.code || -32603, message: error.message }, id }
        : null;
    }
  }));

  res.json(responses.filter(r => r != null));
});

Коли використовувати JSON-RPC

Ідеально для: блокчейн/крипто API, мовних серверів, простої внутрішньої microservice комунікації. Не підходить для: публічних API, що вимагають семантики ресурсів, браузерних клієнтів, що очікують REST конвенцій.

Терміни

Базовий JSON-RPC сервер (10–15 методів): 2–3 дні. Зі стримингом, батчингом, розширеною обробкою помилок: 4–5 днів.