Algorand API Tools

This package contains tools for working with the Algorand API specifications and generating Rust HTTP client libraries using a custom Jinja2-based generator.

Prerequisites

• Python 3.12+ - Required for the custom OAS generator
• uv - Python package manager
• Rust - Required for compiling generated clients and running API tools
• Node.js - JavaScript runtime (only for convert-openapi script)

Setup

# Install Python dependencies for the OAS generator
cd api/oas_generator
uv install

# Install JavaScript dependencies (only needed for convert-openapi)
cd ../
npm install

Available Scripts

NOTE: These scripts can be run from the repository root using cargo api <command>.

Convert OpenAPI 2.0 to OpenAPI 3.0

Converts the Algod, Indexer, and KMD OpenAPI 2.0 specs to OpenAPI 3.0:

cargo api convert-openapi

Convert individual specifications:

# Convert only algod spec
cargo api convert-algod

# Convert only indexer spec
cargo api convert-indexer

# Convert only kmd spec
cargo api convert-kmd

The converted specs will be available at:

• specs/algod.oas3.json
• specs/indexer.oas3.json
• specs/kmd.oas3.json

Generate Rust API Clients

Generate all Rust API clients using the custom Jinja2-based generator:

cargo api generate-all

Generate individual clients:

# Generate algod client only
cargo api generate-algod

# Generate indexer client only
cargo api generate-indexer

# Generate kmd client only
cargo api generate-kmd

The generated Rust clients will be available at:

• ../crates/algod_client/
• ../crates/indexer_client/
• ../crates/kmd_client/

Development Scripts

# Test the OAS generator
cargo api test-oas

# Format the OAS generator code
cargo api format-oas

# Lint and type-check the OAS generator
cargo api lint-oas

# Format generated Rust code
cargo api format-algod
cargo api format-indexer
cargo api format-kmd

Custom Rust OAS Generator

The project uses a custom Jinja2-based generator located in oas_generator/ that creates optimized Rust API clients from OpenAPI 3.x specifications.

Features

• Complete Rust Client Generation: APIs, models, and configuration
• Msgpack Support: Automatic detection and handling of binary encoding
• Signed Transactions: Algorand-specific vendor extension support (x-algokit-signed-txn)
• Type Safety: Comprehensive OpenAPI to Rust type mapping
• Template-based: Customizable Jinja2 templates for code generation

Generated Structure

The generator creates complete Rust crates with the following structure:

crates/{algod_client,indexer_client,kmd_client}/
├── Cargo.toml
├── README.md
└── src/
    ├── lib.rs
    ├── apis/
    │   ├── mod.rs
    │   ├── client.rs
    │   └── {endpoint}.rs
    └── models/
        ├── mod.rs
        └── {model}.rs

OpenAPI Specs for Algorand APIs

Algod

The algod.oas2.json is taken directly from go-algorand. To convert the spec to OpenAPI 3.0, use cargo api convert-algod which runs the TypeScript script scripts/convert-openapi.ts via swagger converter endpoint.

Indexer

The indexer.oas2.json is taken directly from indexer. To convert the spec to OpenAPI 3.0, use cargo api convert-indexer which runs the same TypeScript conversion script.

KMD

The KMD Swagger 2.0 specification is sourced from go-algorand. Convert it to OpenAPI 3.0 with cargo api convert-kmd which invokes scripts/convert-openapi.ts.

The current approach is to manually edit and tweak the OAS2 specs fixing known issues from the source repositories, then use the custom Rust OAS generator to generate clients from the v3 specs. OpenAPI v3 is preferred for client generation as it offers enhanced schema features, better component reusability, and improved type definitions compared to v2.

Generator Configuration

The custom Rust generator is configured with:

• Package names: algod_client, indexer_client, kmd_client
• Msgpack detection: Automatic handling of binary-encoded fields
• Algorand extensions: Support for signed transaction via a vendor extension
• Type safety: Complete OpenAPI to Rust type mapping
• Error handling: Comprehensive error types and response handling

For detailed information about the generator architecture and customization options, see oas_generator/ARCHITECTURE.md.