Sources

A Source defines an API endpoint that your mission connects to. Sources configure authentication, base URLs, rate limiting, and other HTTP client options.

Basic syntax

source SourceName {
  auth: authType,
  base: "https://api.example.com"
}

Authentication types

The auth: value is just the type; there's no sub-config in the DSL, and credentials never go in the source {} block. They come from an auth file (--auth <file>) or environment variables.

Type	Description
none	No authentication
bearer	Bearer token in the Authorization header
basic	HTTP Basic authentication
api_key	API key in a request header or query parameter
oauth2	OAuth 2.0 with token refresh

:::note Missing credentials fail loudly All five types attach credentials at runtime. An auth type configured without the credentials it needs throws when the source is initialized rather than sending the request unauthenticated. :::

No authentication

source PublicAPI {
  auth: none,
  base: "https://jsonplaceholder.typicode.com"
}

Bearer token

source GitHub {
  auth: bearer,
  base: "https://api.github.com"
}

Credentials are provided via CLI or config:

{
  "GitHub": {
    "type": "bearer",
    "token": "ghp_xxxxxxxxxxxx"
  }
}

API Key

source StripeAPI {
  auth: api_key,
  base: "https://api.stripe.com/v1"
}

{
  "StripeAPI": {
    "type": "api_key",
    "apiKey": "sk_live_xxxx",
    "headerName": "X-API-Key"
  }
}

headerName defaults to X-API-Key. Set apiKeyLocation: "query" to send the key as a query parameter instead; see API key authentication for the details.

Basic authentication

source LegacyAPI {
  auth: basic,
  base: "https://legacy.example.com"
}

{
  "LegacyAPI": {
    "type": "basic",
    "username": "user",
    "password": "pass"
  }
}

OAuth 2.0

source Xero {
  auth: oauth2,
  base: "https://api.xero.com/api.xro/2.0"
}

{
  "Xero": {
    "type": "oauth2",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "accessToken": "current-access-token",
    "refreshToken": "current-refresh-token",
    "tokenEndpoint": "https://identity.xero.com/connect/token"
  }
}

Reqon refreshes tokens when they expire, but the refreshed token is held in memory only for the current run.

OpenAPI spec sources

Load source configuration from an OpenAPI specification:

source Petstore from "./petstore.yaml" {
  auth: bearer,
  validateResponses: true
}

Benefits:

• Base URL extracted from spec
• Operations available via call syntax
• Response validation against schemas

See OpenAPI Integration for details.

Source options

Custom headers

source CustomAPI {
  auth: bearer,
  base: "https://api.example.com",
  headers: {
    "X-Custom-Header": "value",
    "Accept": "application/json"
  }
}

Values are expressions, so env("API_VERSION") works. Headers apply to every request through the source; an auth provider's own headers win if a name collides.

Rate limiting

source RateLimitedAPI {
  auth: bearer,
  base: "https://api.example.com",
  rateLimit: {
    strategy: pause,
    maxWait: 300,
    fallbackRpm: 60
  }
}

Options:

• strategy (unquoted identifier) - one of pause, throttle, or fail
• maxWait - longest wait in seconds before giving up (default 300)
• fallbackRpm - requests per minute to assume when the API sends no rate-limit headers (default 60)
• model - a description of the server's own limiter so throttle can pace under it; see Rate limiting

Strategies:

• pause - wait when the limit is reached
• throttle - slow down requests
• fail - throw an error when the limit is reached

Circuit breaker

Prevent cascading failures:

source UnreliableAPI {
  auth: bearer,
  base: "https://flaky-api.example.com",
  circuitBreaker: {
    failureThreshold: 5,
    resetTimeout: 30,
    successThreshold: 2
  }
}

The full set of options is failureThreshold (default 5), resetTimeout in seconds (default 30), successThreshold (default 2), failureWindow in seconds (default 60), and the rate-based pair failureRate and minimumRequests (default 20). See Circuit Breaker for details.

Using sources

The first defined source is used by default. To target another source, set the source option on the request:

mission MultiSource {
  source Primary { auth: bearer, base: "https://primary.example.com" }
  source Secondary { auth: bearer, base: "https://secondary.example.com" }

  action FetchFromPrimary {
    // Uses the first source by default
    get "/data"
  }

  action FetchFromSecondary {
    // Explicitly use the secondary source
    get "/data" { source: Secondary }
  }
}

Default source

The first defined source is the default:

mission Example {
  source API { auth: bearer, base: "https://api.example.com" }

  action Fetch {
    get "/users"  // Uses API source
  }
}

Named source reference

Set the source option to pick a source per request:

action FetchFromMultiple {
  get "/users" { source: Primary }
  get "/users" { source: Secondary }
}

Best practices

Use descriptive names

// Good
source XeroAccounting { }
source QuickBooksOnline { }
source StripePayments { }

// Avoid
source API1 { }
source Source { }

Always use rate limiting for production

source ProductionAPI {
  auth: bearer,
  base: "https://api.example.com",
  rateLimit: {
    strategy: pause,
    fallbackRpm: 100
  }
}

Enable circuit breakers for unreliable sources

source ThirdPartyAPI {
  auth: bearer,
  base: "https://third-party.example.com",
  circuitBreaker: {
    failureThreshold: 5,
    resetTimeout: 30000
  }
}