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

```json
{
  "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

```json
{
  "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

```bash
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)

```bash
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

```bash
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:

```json
{
  "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:
```json
{
  "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:

```json
{
  "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

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

Response:
```json
{
  "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