Batch (Multi) Requests

Batch requests in PulsePI allow you to call multiple modules and/or actions in a single request, reducing network overhead and improving performance.

Batch Request Structure

A batch request uses arrays for the module, action, and params fields:

module: Array of module names
action: Array of actions (can contain nested arrays for multiple actions per module)
params: Array of parameter objects, one for each action

Basic Batch Example

json

{
  "module": ["posts", "user"],
  "action": ["getPosts", "list"],
  "params": [{}, {}]
}

This request calls the getPosts action in the posts module and the list action in the user module.

Multiple Actions per Module

json

{
  "module": ["posts", "user"],
  "action": [["getPosts", "getUsers"], "list"],
  "params": [{}, {}, {}]
}

This request calls:

posts.getPosts (first action)
posts.getUsers (second action)
user.list (third action)

The params array must have one object for each action, in the same order.

Complex Batch Example

json

{
  "module": ["posts", "user", "blog"],
  "action": [["getPosts", "getUsers"], "list", "getTrendingPosts"],
  "params": [
    { "_fields": ["title", "content"] },
    { "_fields": ["author", "category"] },
    { "_fields": ["name", "email"] },
    { "_fields": ["title", "viewCount"] }
  ]
}

This request calls multiple actions with specific field projections for each:

posts.getPosts → returns only title and content
posts.getUsers → returns only author and category
user.list → returns only name and email
blog.getTrendingPosts → returns only title and viewCount

Batch Response Format

A successful batch request returns a response with this structure:

json

{
  "status": "multi-success",
  "results": {
    "posts": {
      "getPosts": [
        {
          "id": 1,
          "title": "Getting Started with PulsePI"
        },
        {
          "id": 2,
          "title": "Advanced PulsePI Techniques"
        }
      ],
      "getUsers": [
        {
          "id": 1,
          "name": "John Doe"
        },
        {
          "id": 2,
          "name": "Jane Smith"
        }
      ]
    },
    "user": {
      "list": [
        {
          "_id": "6800e57a2631bfc62c9e3d30"
        },
        {
          "_id": "6800fa432df5c382263faee5",
          "name": "Test1",
          "email": "test@mail.com"
        }
      ]
    },
    "blog": {
      "getTrendingPosts": [
        {
          "id": 1,
          "title": "Why PulsePI is the Future of APIs"
        },
        {
          "id": 2,
          "title": "PulsePI vs GraphQL: A Comparison"
        }
      ]
    }
  },
  "meta": {
    "executedAt": "2025-04-17T14:00:00.000Z"
  }
}

status: "multi-success" for successful batch requests
results: Nested object with modules as keys and actions as sub-keys
meta: Metadata about the request execution

Best Practices

Group related operations in batch requests to reduce network overhead
Keep batch sizes reasonable (5-10 operations maximum)
Use specific field projections for each action to minimize response size
Handle partial failures by checking the status of each result