Overview

What is apiexec?

A vendor-agnostic streaming execution engine that turns unreliable API calls into a deterministic, streaming data retrieval model. It handles retry, backoff, adaptive chunking, pagination, and cost budgets internally - exposing a clean Stream<T> interface upward and delegating API-specific logic to swappable VendorAdapter<T> implementations downward.

Common use cases:

• Paginating any REST API - point generic_rest at a cursor-based endpoint; apiexec drives the pagination loop, retries, and prefetch automatically
• Streaming Datadog metrics - datadog_metrics handles time-windowing, adaptive chunk sizing, and rate-limit backoff
• AI inference with cost budgets - openai and anthropic adapters track token spend via response_cost(); a CostAwarePolicy halts the stream when the budget is reached

Adapters

Four adapters ship with the library. All are registered at process startup via static initialisers - no explicit registration call required.

See Adapters for the full config key reference and example JSON configs.

Language Bindings

The C++ core is hidden behind an ABI-stable C header (c_api/c_api.h). Every language reaches the engine through its native FFI mechanism:

All bindings share the same semantics: one stream_create, one stream_destroy, caller-owned buffers, and int32_t error codes. See Quick Start for per-language setup instructions.

Design Goals

• ABI stability first. The C API header is the freeze point. Adding functionality means adding new versioned symbols - never mutating existing ones.
• Null-safe by contract. Every pointer parameter is null-checked before dereference. Callers get a well-defined error code, not a crash.
• Caller-owned memory. The C API never allocates buffers visible to the caller. All scratch space is passed in, so bindings control their own lifetimes.
• One-way ownership. Handles are created by the library and destroyed by a single dedicated function. No silent frees. No shared mutable state.

Ownership Model at a Glance

#include "c_api.h"

const char* config = "{\"base_url\": \"https://api.example.com/v1/data\"}";
StreamHandle* h = stream_create("generic_rest", config, NULL);
if (!h) { /* out of memory or bad config */ }

char buf[1048576];
int32_t count = 0;
while (stream_has_next(h) == 1) {
    int32_t rc = stream_next_batch_v1(h, buf, sizeof buf, &count);
    if (rc != STREAM_OK) break;
    printf("Got %d records: %s\n", count, buf);
}

stream_destroy(h);  // the only valid deallocation path

A few things to notice:

• stream_create returns a heap-allocated handle. The caller owns it.
• stream_destroy is the only valid way to release a handle. Calling free() directly is undefined behaviour.
• buf is caller-allocated. apiexec never allocates caller-visible memory.
• stream_destroy(NULL) and stream_cancel(NULL) are safe no-ops.

Metrics

apiexec tracks 11 runtime counters per stream (request count, retry count, error breakdown, window size, cumulative cost). The engine exposes them via a callback and a Prometheus text formatter - no metrics library dependency required. See Metrics.

Where To Go Next

• Quick Start - build, link, and write your first stream in any language
• Architecture - understand the VendorAdapter / Stream<T> / C ABI model
• Adapters - config keys and examples for all four built-in adapters
• Stream API - full function table, error codes, and null-safety contract
• Metrics - runtime observability, Prometheus export, and language binding support
• Examples - real-world patterns across all languages