OpenRPCMethods

Batch Requests

Document how to handle multiple JSON-RPC calls in a single request

Batch requests in JSON-RPC allow clients to send multiple method calls in a single HTTP request, improving efficiency and reducing network overhead. OpenRPC supports documenting batch request capabilities.

Batch request structure

While individual methods are documented separately, batch requests combine multiple calls:

Batch Request Example
1[
2  {
3    "jsonrpc": "2.0",
4    "method": "user.get",
5    "params": { "id": "user_123" },
6    "id": 1
7  },
8  {
9    "jsonrpc": "2.0",
10    "method": "order.list",
11    "params": { "userId": "user_123", "limit": 10 },
12    "id": 2
13  },
14  {
15    "jsonrpc": "2.0",
16    "method": "analytics.track",
17    "params": {
18      "event": {
19        "userId": "user_123",
20        "eventType": "api_call",
21        "properties": { "endpoint": "batch_request" }
22      }
23    }
24  }
25]

Documenting batch-capable methods

Mark methods that work well in batch scenarios:

openrpc.yml
1methods:
2  - name: user.get
3    summary: Get user by ID
4    x-fern-batch-compatible: true
5    x-fern-batch-description: "Efficiently retrieve multiple users in a single batch"
6    params:
7      - name: id
8        schema:
9          type: string
10        required: true
11    result:
12      name: user
13      schema:
14        $ref: '#/components/schemas/User'
15  - name: product.get
16    summary: Get product by ID
17    x-fern-batch-compatible: true
18    x-fern-batch-description: "Retrieve multiple products with a single request"
19    params:
20      - name: id
21        schema:
22          type: string
23        required: true
24    result:
25      name: product
26      schema:
27        $ref: '#/components/schemas/Product'

Batch response handling

Document how batch responses are structured:

openrpc.yml
1info:
2  title: E-commerce API
3  version: 1.0.0
4  description: |
5    This API supports JSON-RPC batch requests for improved performance.
6    
7    Batch responses maintain the same order as requests and include:
8    - Successful results with matching request IDs
9    - Error responses for failed calls
10    - No response for notification calls (calls without IDs)
11    
12    Example batch response:
13    ```json
14    [
15      {
16        "jsonrpc": "2.0",
17        "result": { "id": "user_123", "name": "John Doe" },
18        "id": 1
19      },
20      {
21        "jsonrpc": "2.0",
22        "result": [{ "id": "order_456", "total": 99.99 }],
23        "id": 2
24      }
25    ]
## Mixed batch requests
Document scenarios with regular methods and notifications:
```yml title="openrpc.yml" {2-23}
methods:
  - name: order.create
    summary: Create a new order
    description: Can be used in batch requests with order.calculate for atomic operations
    x-fern-batch-compatible: true
    params:
      - name: orderData
        schema:
          $ref: '#/components/schemas/CreateOrderRequest'
        required: true
    result:
      name: order
      schema:
        $ref: '#/components/schemas/Order'
  - name: order.calculate
    summary: Calculate order totals
    description: Often used before order.create in batch requests
    x-fern-batch-compatible: true
    params:
      - name: items
        schema:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        required: true
    result:
      name: calculation
      schema:
        $ref: '#/components/schemas/OrderCalculation'
    examples:
      - name: BatchOrderProcessing
        description: Calculate and create order in a single batch
        params:
          items:
            - productId: "prod_123"
              quantity: 2
              price: 29.99
            - productId: "prod_456"
              quantity: 1
              price: 15.50
        result:
          subtotal: 75.48
          tax: 6.04
          shipping: 5.99
          total: 87.51

Error handling in batches

Document how errors are handled in batch scenarios:

openrpc.yml
1info:
2  title: API Documentation
3  version: 1.0.0
4  description: |
5    ## Batch Error Handling
6    
7    When processing batch requests:
8    - Each call is processed independently
9    - Successful calls return normal results
10    - Failed calls return error objects
11    - Notifications (calls without ID) produce no response
12    - Partial failures are allowed - some calls can succeed while others fail
13    
14    Error response example:
15    ```json
16    {
17      "jsonrpc": "2.0",
18      "error": {
19        "code": -32602,
20        "message": "Invalid params",
21        "data": { "field": "email", "error": "Invalid email format" }
22      },
23      "id": 3
24    }
## Batch optimization methods
Document methods specifically designed for batch operations:
```yml title="openrpc.yml" {2-19}
methods:
  - name: users.getBatch
    summary: Get multiple users by IDs
    description: Optimized method for retrieving multiple users in a single call
    params:
      - name: userIds
        schema:
          type: array
          items:
            type: string
          maxItems: 100
          minItems: 1
        required: true
        description: Array of user IDs to retrieve (max 100)
    result:
      name: users
      schema:
        type: object
        properties:
          users:
            type: array
            items:
              $ref: '#/components/schemas/User'
          notFound:
            type: array
            items:
              type: string
            description: IDs that were not found
        required:
          - users
          - notFound
    examples:
      - name: GetMultipleUsers
        description: Retrieve several users at once
        params:
          userIds: ["user_123", "user_456", "user_789"]
        result:
          users:
            - id: "user_123"
              name: "John Doe"
              email: "john@example.com"
            - id: "user_456"
              name: "Jane Smith"
              email: "jane@example.com"
          notFound: ["user_789"]

Batch size limitations

Document batch request limits and recommendations:

openrpc.yml
1info:
2  title: API with Batch Support
3  version: 1.0.0
4  x-fern-batch-limits:
5    maxBatchSize: 50
6    maxPayloadSize: "1MB"
7    timeoutSeconds: 30
8    description: "Batch requests are limited to 50 operations or 1MB payload size"
9  description: |
10    ## Batch Request Guidelines
11    
12    - Maximum 50 operations per batch request
13    - Total payload size limited to 1MB
14    - Batch processing timeout: 30 seconds
15    - Use batch requests for:
16      - Retrieving related data in a single round-trip
17      - Performing multiple updates atomically
18      - Reducing network overhead for mobile applications
19    
20    - Avoid batch requests for:
21      - Long-running operations (use individual calls)
22      - Operations that don't benefit from batching
23      - Calls that might exceed timeout limits

SDK batch support

Configure how SDKs handle batch requests:

openrpc.yml
1components:
2  x-fern-batch-config:
3    enableBatchMethods: true
4    generateBatchHelpers: true
5    batchMethodNaming: "batch{MethodName}"
6    maxBatchSize: 50

This configuration would generate SDK methods like:

1// Individual calls
2const user = await client.user.get({ id: "user_123" });
3const product = await client.product.get({ id: "prod_456" });
4
5// Batch call
6const results = await client.batch([
7  { method: "user.get", params: { id: "user_123" } },
8  { method: "product.get", params: { id: "prod_456" } },
9  { method: "analytics.track", params: { event: {...} } } // notification
10]);

Batch requests are essential for high-performance applications that need to minimize network round-trips while maintaining the flexibility of individual method calls.