Configuration Overview

Configuration Overview

ApiCharge uses a combination of configuration files and environment variables to manage its settings. This guide explains the different configuration components and how they work together.

Configuration Components

ApiCharge's configuration is divided into several components:

• appsettings.json: The main configuration file containing all service settings
• appsettings.{Environment}.json: Environment-specific overrides (e.g., appsettings.Development.json)
• Environment Variables: Sensitive settings and deployment-specific configurations
• Command Line Arguments: Override specific settings at runtime

Main Configuration File Structure

The appsettings.json file contains several top-level sections:

{
  "Logging": {
    // Logging configuration settings
  },
  "GlobalSettings": {
    // ApiCharge global settings (network, contract IDs, etc.)
  },
  "CacheSettings": {
    // Caching configuration for rate limiters
  },
  "ApiChargeProxy": {
    // YARP proxy configuration with routes and clusters
    "Routes": { },
    "Clusters": { }
  },
  "ApiChargeQuotes": {
    // Quote configuration for monetized routes
  },
  "Kestrel": {
    // Web server configuration
  }
}

Configuration Priorities

ApiCharge follows a specific order of precedence when resolving configuration values:

1. Command Line Arguments: Highest priority
2. Environment Variables: Second priority
3. appsettings.{Environment}.json: Third priority
4. appsettings.json: Lowest priority (base configuration)

This hierarchy allows you to provide a base configuration in appsettings.json and then override specific values based on the deployment environment.

Global Settings

The GlobalSettings section defines core ApiCharge parameters like:

• Network type (Testnet or Mainnet)
• Stellar contract IDs
• Blockchain endpoints
• Clock skew tolerances
• Quote validity durations
• SSL/TLS certificate validation settings

For detailed information about global settings, see the Global Settings page.

Environment Variables

Environment variables are used for sensitive information like private keys and for deployment-specific settings. Critical environment variables include:

• APICHARGE_SIGNING_KEY: The service's ED25519 signing private key
• APICHARGE_NETWORK_PASSPHRASE: The Stellar network passphrase
• ASPNETCORE_URLS: Web server binding addresses and ports
• ASPNETCORE_ENVIRONMENT: Runtime environment name (Development, Production, etc.)

For a comprehensive list of environment variables, see the Environment Variables page.

Logging Configuration

The Logging section configures the logging behavior of ApiCharge. It allows you to set log levels for different components and configure logging providers:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

For detailed information about logging configuration, see the Logging Configuration page.

Cache Settings

The CacheSettings section configures the caching system used for rate limiter persistence. ApiCharge supports two caching options:

{
  "CacheSettings": {
    "UseRedis": true,
    "Redis": {
      "ConnectionString": "localhost:6379",
      "InstanceName": "ApiCharge:"
    },
    "MemoryCache": {
      "SizeLimit": 104857600  // 100MB cache limit
    }
  }
}

For production deployments, Redis is recommended for scalability and persistence across service restarts.

ApiChargeProxy Configuration

The ApiChargeProxy section contains the YARP reverse proxy configuration with two main subsections:

1. Routes: Defines the API routes that clients can access
2. Clusters: Specifies the backend services that requests are forwarded to

This section is critical for defining how client requests are mapped to backend services. For detailed information about routes configuration, see the Routes Overview page.

Quote Configuration

The ApiChargeQuotes section defines the pricing and quality of service parameters for each route:

{
  "ApiChargeQuotes": {
    "Quotes": [
      {
        "RouteId": "basic-route",
        "Duration": 3600,
        "MicroUnitPrice": 100000,
        "RateLimiters": [
          {
            "$type": "CallCount",
            "Count": 100
          }
        ]
      }
    ]
  }
}

This configuration defines what quotes are offered to clients when they request service access.

Kestrel Web Server Configuration

The Kestrel section configures the underlying web server, including:

• HTTP/HTTPS endpoints
• SSL certificate settings
• Connection limits
• Request timeouts

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://0.0.0.0:80"
      },
      "Https": {
        "Url": "https://0.0.0.0:443",
        "Certificate": {
          "Path": "certificate.pfx",
          "Password": "cert_password"
        }
      }
    }
  }
}

Configuration Hot Reload

ApiCharge monitors the appsettings.json and appsettings.{Environment}.json files for changes. When a change is detected, the configuration is automatically reloaded without restarting the service.

This feature allows you to update routes, quotes, and other settings in real-time. Note that some settings may require a service restart to take effect (e.g., Kestrel endpoints).

Next Steps

To learn more about specific configuration components, explore:

• Global Settings - Core ApiCharge settings
• Environment Variables - Security-sensitive settings
• Routes Overview - Configuring API routes