pyRPC
← Back to Blog

Batch requests in pyRPC: how they work and when to use them

·4 min read

pyRPC supports batching since v0.13.0. A batch request sends multiple RPC operations in a single HTTP call, reducing network overhead and latency. With v0.14.1, batch requests now work correctly across all adapters including FastAPI.

What a batch request looks like

Instead of sending one JSON-RPC object, you send an array of them:

POST /rpc
Content-Type: application/json

[
  {"id": 1, "method": "add", "params": {"a": 10, "b": 5}},
  {"id": 2, "method": "greet", "params": {"user": {"name": "Alice", "age": 30}}}
]

The server processes each operation and returns an array of responses:

[
  {"id": 1, "result": 15},
  {"id": 2, "result": "Hello, Alice!"}
]

Using httpBatchLink

On the TypeScript side, swap httpLink for httpBatchLink:

import { createClient, httpBatchLink } from "@pyrpc/client"
import type { Types } from "@pyrpc/types"

const api = createClient<Types>({
  links: [
    httpBatchLink({
      url: "http://localhost:8000",
    }),
  ],
})

// These two calls are sent as a single HTTP request
const result = await api.add(10, 5)
const message = await api.greet({ name: "Alice", age: 30 })

How the server handles batches

Inside handle_request, a batch is processed sequentially:

if isinstance(payload, list):
    if len(payload) > MAX_BATCH_SIZE:
        return {"error": "Batch too large"}
    return [_handle_single(op, router) for op in payload]

Each operation goes through the same validation and execution path as a single request. The MAX_BATCH_SIZE limit (100 operations) guards against abuse.

When to batch

  • Page loads that need multiple data sources. Instead of 5 sequential HTTP calls for user data, posts, comments, notifications, and settings, send one batch.
  • Form submissions with side effects. A mutation that creates an order and a query that fetches the updated cart can run in the same request.
  • Dashboard initial loads. Charts, tables, and summary cards often need different procedures — batch them.

Batching is not always better. If operations depend on each other's results, sequential single requests are clearer. If you are sending one operation, httpLink is simpler.

Adapter compatibility

All four adapters now support batch requests:

  • FastAPI — fixed in v0.14.1 (payload annotation widened)
  • Flask — always worked (raw JSON parse)
  • Django — always worked (raw JSON parse)
  • ASGI — always worked (raw JSON parse)