Skip to main content

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​

TypeDescription
noneNo authentication
bearerBearer token in Authorization header
basicHTTP Basic authentication
api_keyAPI key in header or query
oauth2OAuth 2.0 with token refresh

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",
    "key": "sk_live_xxxx",
    "header": "Authorization",
    "prefix": "Bearer"
  }
}

Or in query parameter:

{
  "StripeAPI": {
    "type": "api_key",
    "key": "sk_live_xxxx",
    "query": "api_key"
  }
}

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",
    "tokenUrl": "https://identity.xero.com/connect/token",
    "scopes": ["accounting.transactions.read"]
  }
}

Reqon automatically refreshes tokens when they expire.

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"
  }
}

Rate limiting​

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

Strategies:

  • pause - Wait when limit reached
  • throttle - Slow down requests
  • fail - Throw error when limit reached

Circuit breaker​

Prevent cascading failures:

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

See Circuit Breaker for details.

Timeout​

source SlowAPI {
  auth: bearer,
  base: "https://slow-api.example.com",
  timeout: 60000
}

Using sources​

Sources are automatically selected when making requests:

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

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

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

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​

Prefix requests with source name:

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

Source variables​

Use environment variables in source definitions:

source API {
  auth: bearer,
  base: env("API_BASE_URL")
}

Multiple environments​

Pattern for handling different environments:

mission Sync {
  source API {
    auth: bearer,
    base: match env("ENVIRONMENT") {
      "production" => "https://api.example.com",
      "staging" => "https://staging.api.example.com",
      _ => "http://localhost:3000"
    }
  }
}

Best practices​

Use descriptive names​

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

// Avoid
source API1 { }
source Source { }

Configure appropriate timeouts​

// For fast APIs
source FastAPI {
  timeout: 5000  // 5 seconds
}

// For slow/bulk APIs
source BulkExportAPI {
  timeout: 300000  // 5 minutes
}

Always use rate limiting for production​

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

Enable circuit breakers for unreliable sources​

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