Quickstart Guide

This guide will help you get started with apiout in minutes.

Installation

Install apiout using pip:

pip install apiout

Basic Usage

1. Without Serializers (Auto-serialize)

Create a file apis.toml:

[[apis]]
name = "berlin_weather"
module = "openmeteo_requests"
client_class = "Client"
method = "weather_api"
url = "https://api.open-meteo.com/v1/forecast"

[apis.params]
latitude = 52.52
longitude = 13.41
current = ["temperature_2m"]

Run the fetcher:

apiout run --config apis.toml --json

The tool will automatically convert response objects to dictionaries.

2. With Inline Serializers

Add serializer configuration to the same file:

[serializers.openmeteo]
[serializers.openmeteo.fields]
latitude = "Latitude"
longitude = "Longitude"

[serializers.openmeteo.fields.current]
method = "Current"
[serializers.openmeteo.fields.current.fields]
time = "Time"

[[apis]]
name = "berlin_weather"
module = "openmeteo_requests"
client_class = "Client"
method = "weather_api"
url = "https://api.open-meteo.com/v1/forecast"
serializer = "openmeteo"

[apis.params]
latitude = 52.52
longitude = 13.41
current = ["temperature_2m"]

Run the same command:

apiout run --config apis.toml --json

3. With Separate Serializer File

Create apis.toml:

[[apis]]
name = "berlin_weather"
module = "openmeteo_requests"
client_class = "Client"
method = "weather_api"
url = "https://api.open-meteo.com/v1/forecast"
serializer = "openmeteo"

[apis.params]
latitude = 52.52
longitude = 13.41
current = ["temperature_2m"]

Create serializers.toml:

[serializers.openmeteo]
[serializers.openmeteo.fields]
latitude = "Latitude"
longitude = "Longitude"

[serializers.openmeteo.fields.current]
method = "Current"
[serializers.openmeteo.fields.current.fields]
time = "Time"

Run with both files:

apiout run --config apis.toml --serializers serializers.toml --json

4. With Reusable Client Configurations

When multiple APIs use the same client, define it once and reference it:

[clients.mempool]
module = "pymempool"
client_class = "MempoolAPI"
init_params = {api_base_url = "https://mempool.space/api/"}

[[apis]]
name = "block_tip_hash"
client = "mempool"
method = "get_block_tip_hash"

[[apis]]
name = "block_tip_height"
client = "mempool"
method = "get_block_tip_height"

[[apis]]
name = "recommended_fees"
client = "mempool"
method = "get_recommended_fees"

Run the command:

apiout run --config apis.toml --json

This eliminates repetition when multiple APIs share the same client configuration.

5. With JSON Input

You can provide configuration as JSON via stdin instead of TOML files:

echo '{
  "apis": [{
    "name": "berlin_weather",
    "module": "openmeteo_requests",
    "client_class": "Client",
    "method": "weather_api",
    "url": "https://api.open-meteo.com/v1/forecast",
    "params": {
      "latitude": 52.52,
      "longitude": 13.41,
      "current": ["temperature_2m"]
    }
  }]
}' | apiout run --json

Or convert TOML to JSON using taplo:

taplo get -f apis.toml -o json | apiout run --json

CLI Commands

run

Fetch API data with configuration:

apiout run --config <config.toml> [--serializers <serializers.toml>] [--json]
<json-source> | apiout run [--json]  # Read JSON config from stdin

Options:

• -c, --config: Config file to load (can be specified multiple times). Accepts: - Config name (e.g., mempool) → loads from ~/.config/apiout/mempool.toml - File path (e.g., ./local.toml or /abs/path/config.toml)

• -s, --serializers: Serializer file to load (can be specified multiple times). Accepts: - Serializer name (e.g., my_serializers) → loads from ~/.config/apiout/my_serializers.toml - File path (e.g., ./serializers.toml or /abs/path/serializers.toml)

• -p, --param: Method parameter in format key=value (can be specified multiple times)

• --json: Output as JSON format (default: pretty-printed)

When piping JSON to stdin (without -c), apiout automatically detects and parses it.

generate

Generate serializer configuration by introspecting an API:

apiout generate \
  --module openmeteo_requests \
  --client-class Client \
  --method weather_api \
  --url "https://api.open-meteo.com/v1/forecast" \
  --params '{"latitude": 52.52, "longitude": 13.41, "current": ["temperature_2m"]}' \
  --name openmeteo

Options:

• -m, --module: Python module name (required)

• -c, --client-class: Client class name (default: “Client”)

• --method: Method name to call (required)

• -u, --url: API URL (required)

• -p, --params: JSON params dict (default: “{}”)

• -n, --name: Serializer name (default: “generated”)

Next Steps

• Read the User Guide for detailed information on configuration options

• Check out Examples for more complex use cases

• Explore the API Reference for programmatic usage