michaelschiemer/docs/batch-api-examples.md

Batch API Examples

The Batch API allows you to send multiple HTTP requests in a single batch request, improving efficiency by reducing round-trips and enabling concurrent processing.

Basic Usage

Batch Request Structure

{
  "operations": [
    {
      "id": "get-user-1",
      "method": "GET",
      "path": "/api/examples/users/1",
      "headers": {
        "Authorization": "Bearer token123"
      }
    },
    {
      "id": "create-post",
      "method": "POST", 
      "path": "/api/examples/posts",
      "headers": {
        "Content-Type": "application/json"
      },
      "body": "{\"title\": \"Hello World\", \"content\": \"This is my first post\"}"
    }
  ],
  "continue_on_error": false
}

Batch Response Structure

{
  "responses": [
    {
      "id": "get-user-1",
      "status": 200,
      "headers": {
        "Content-Type": "application/json"
      },
      "body": "{\"id\": 1, \"name\": \"User 1\", \"email\": \"user1@example.com\"}"
    },
    {
      "id": "create-post",
      "status": 201,
      "headers": {
        "Content-Type": "application/json"
      },
      "body": "{\"id\": 1234, \"title\": \"Hello World\", \"content\": \"This is my first post\"}"
    }
  ],
  "total": 2,
  "successful": 2,
  "failed": 0
}

Example Requests

Simple GET Operations

curl -X POST https://localhost/api/batch \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "operations": [
      {
        "id": "user-1",
        "method": "GET", 
        "path": "/api/examples/users/1"
      },
      {
        "id": "user-2",
        "method": "GET",
        "path": "/api/examples/users/2"
      }
    ]
  }'

Mixed Operations (CRUD)

curl -X POST https://localhost/api/batch \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "operations": [
      {
        "id": "create-post",
        "method": "POST",
        "path": "/api/examples/posts",
        "headers": {"Content-Type": "application/json"},
        "body": "{\"title\": \"New Post\", \"content\": \"Great content\"}"
      },
      {
        "id": "update-post", 
        "method": "PUT",
        "path": "/api/examples/posts/123",
        "headers": {"Content-Type": "application/json"},
        "body": "{\"title\": \"Updated Post\", \"content\": \"Updated content\"}"
      },
      {
        "id": "delete-post",
        "method": "DELETE",
        "path": "/api/examples/posts/456"
      }
    ],
    "continue_on_error": true
  }'

With Query Parameters

curl -X POST https://localhost/api/batch \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "operations": [
      {
        "id": "slow-operation",
        "method": "GET",
        "path": "/api/examples/slow?delay=2"
      },
      {
        "id": "another-user",
        "method": "GET", 
        "path": "/api/examples/users/3",
        "query": {"include": "profile"}
      }
    ]
  }'

Error Handling

Continue on Error (true)

When continue_on_error is true, all operations will be executed even if some fail:

{
  "operations": [
    {
      "id": "valid-request",
      "method": "GET",
      "path": "/api/examples/users/1"
    },
    {
      "id": "invalid-request", 
      "method": "GET",
      "path": "/api/nonexistent/endpoint"
    }
  ],
  "continue_on_error": true
}

Response:

{
  "responses": [
    {
      "id": "valid-request",
      "status": 200,
      "body": "{\"id\": 1, \"name\": \"User 1\"}"
    },
    {
      "id": "invalid-request",
      "status": 404,
      "error": "Not Found"
    }
  ],
  "total": 2,
  "successful": 1,
  "failed": 1
}

Stop on First Error (false)

When continue_on_error is false, processing stops at the first error:

{
  "operations": [...],
  "continue_on_error": false
}

Performance Considerations

Concurrent Processing

The batch API processes operations concurrently when possible:

• Operations with no dependencies run in parallel
• Maximum concurrent operations: 10 (configurable)
• Large batches are processed in chunks

Limits

• Maximum operations per batch: 100
• Maximum concurrent operations: 10
• Request timeout: 30 seconds
• Supported methods: GET, POST, PUT, DELETE, PATCH

Get Batch Info

curl -X GET https://localhost/api/batch/info \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"

Response:

{
  "max_operations": 100,
  "max_concurrent_operations": 10,
  "supported_methods": ["GET", "POST", "PUT", "DELETE", "PATCH"],
  "continue_on_error_supported": true
}

Best Practices

1. Use meaningful IDs: Each operation should have a unique, descriptive ID
2. Group related operations: Batch operations that are logically related
3. Handle errors gracefully: Use continue_on_error appropriately
4. Respect limits: Don't exceed the maximum operations limit
5. Monitor performance: Large batches may impact server performance
6. Use appropriate methods: Only use HTTP methods that are allowed