Features

RestBook comes with a powerful set of features designed to make API workflow automation simple and efficient.

Environment Variables

RestBook supports environment variable templating throughout the playbook. You can access environment variables using the env namespace:

# In session configuration
sessions:
  api:
    base_url: "{{ env.API_BASE_URL }}"
    auth:
      type: "bearer"
      credentials:
        token: "{{ env.API_TOKEN }}"

# In request data
steps:
  - session: "api"
    request:
      method: POST
      endpoint: "/users"
      data:
        api_key: "{{ env.API_KEY }}"
        environment: "{{ env.DEPLOY_ENV }}"

# In request parameters
steps:
  - session: "api"
    request:
      method: GET
      endpoint: "/search"
      params:
        api_version: "{{ env.API_VERSION }}"

Environment variables are loaded from:

  1. System environment variables
  2. CI/CD environment variables

Session Management

RestBook provides robust session management capabilities:

Parallel Execution

Run steps and iterations concurrently for improved performance:

# Parallel phase execution
phases:
  - name: "Parallel Phase"
    parallel: true
    steps:
      - session: "api"
        request: # ...

# Parallel iteration execution
steps:
  - session: "api"
    iterate: "item in items"
    parallel: true
    request: # ...

Variable Storage and Templates

Store and use data between steps with powerful templating:

steps:
  - session: "api"
    request:
      method: GET
      endpoint: "/users"
    store:
      - var: "users"
        jq: ".[]"  # Store all users

  - session: "api"
    iterate: "user in users"
    request:
      method: POST
      endpoint: "/users/{{ user.id }}/process"
      data:
        name: "{{ user.name }}"
        email: "{{ user.email }}"

Logging

RestBook provides flexible logging capabilities with multiple output formats and configurable log levels:

Output Formats

Choose from three different logging formats:

  1. Colorful (default): Human-readable output with color coding for different log levels
  2. Plain: Simple text output suitable for CI/CD environments
  3. JSON: Machine-readable output for programmatic processing

Log Levels

Control the verbosity of logging with different log levels:

Configuration

Configure logging through command line options or environment variables:

# Command line options
restbook --output json --log-level DEBUG

# Environment variables
RESTBOOK_OUTPUT=json RESTBOOK_LOG_LEVEL=DEBUG restbook

The logging system provides detailed information about:

List Appending

Append to list variables across multiple steps:

steps:
  - session: "api"
    request:
      method: GET
      endpoint: "/users/page/1"
    store:
      - var: "all_users"
        jq: ".users"
        append: true  # Creates a new list

  - session: "api"
    request:
      method: GET
      endpoint: "/users/page/2"
    store:
      - var: "all_users"
        jq: ".users"
        append: true  # Appends to existing list

Error Handling and Retries

Configure robust error handling and retry policies:

steps:
  - session: "api"
    request:
      method: GET
      endpoint: "/users"
    retry:
      max_retries: 3
      backoff_factor: 1.0
      max_delay: 10
      circuit_breaker:
        threshold: 2
        reset: 5
        jitter: 0.1
    timeout: 30
    on_error: ignore  # Continue on error

Features include:

Incremental Execution

Resume workflows after failures with incremental execution:

incremental:
  enabled: true
  store: file
  file_path: "/path/to/checkpoints"

Benefits:

CI/CD Integration

RestBook is designed to work seamlessly in CI/CD environments:

Resilient HTTP Client

RestBook includes a resilient HTTP client that handles retries, circuit breaking, and rate limiting. This ensures that your API requests are reliable even in the face of transient failures.

Retry Configuration

You can configure retry behavior at both the session and step levels:

# Session-level retry configuration
sessions:
  api:
    base_url: "https://api.example.com"
    retry:
      max_retries: 3
      backoff_factor: 1.0
      max_delay: 10

# Step-level retry configuration (overrides session defaults)
phases:
  - name: "Example Phase"
    steps:
      - session: api
        request:
          method: GET
          endpoint: "/users"
        retry:
          max_retries: 5
          backoff_factor: 0.5

Circuit Breaker

Circuit breakers prevent cascading failures by temporarily stopping requests to failing services:

sessions:
  api:
    base_url: "https://api.example.com"
    retry:
      circuit_breaker:
        threshold: 5
        reset: 60
        jitter: 0.1

Rate Limiting

Rate limiting helps prevent overwhelming APIs:

sessions:
  api:
    base_url: "https://api.example.com"
    retry:
      rate_limit:
        use_server_retry_delay: true
        retry_header: "Retry-After"

Metrics Collection

RestBook provides a comprehensive metrics collection system that allows you to monitor and analyze the performance and behavior of your playbooks.

Metrics Collectors

RestBook supports three types of metrics collectors:

  1. JSON Collector: Saves metrics to a JSON file for debugging and CI/CD pipelines
  2. Prometheus Collector: Pushes metrics to a Prometheus Pushgateway for production monitoring
  3. Console Collector: Outputs metrics to the console in real-time for local development

Resource Metrics

RestBook collects detailed resource usage metrics to help you optimize your playbooks:

Configuration Example

metrics:
  enabled: true
  collector: json
  output_file: "metrics_output.json"

For more details, see the Metrics documentation.

Playbook Execution

Development and Testing Features

RestBook provides several features to help with development and testing of playbooks:

Cron-based Execution

For development and testing purposes, RestBook supports running playbooks on a schedule using cron syntax:

restbook playbook run playbook.yaml --cron "*/5 * * * *"

This will execute the playbook every 5 minutes. The cron expression follows standard cron syntax:

Important Note: While this feature is useful for development and testing, it’s recommended to use external schedulers for production environments. This approach:

For production environments, consider using:

Next Steps