Variables

Use variables and templating to create reusable, dynamic HTTP request configurations.

Copy Markdown

Variables in curl-runner allow you to create flexible, reusable configurations. You can define variables at different scopes and use them throughout your request definitions with template interpolation.

Variable Interpolation Syntax

Variables are interpolated using the ${VARIABLE_NAME} syntax, which supports JavaScript expressions and complex logic.

Variable Scopes

Variables can be defined at different levels, each with its own scope and precedence rules.

Global Variables

Global variables are available to all requests in the file and have the lowest precedence.

global-variables.yaml
global:
  variables:
    BASE_URL: "https://api.example.com"
    API_VERSION: "v1"

collection:
  name: "API Tests"
  requests:
    - name: "Get users"
      url: "${BASE_URL}/${API_VERSION}/users"
      method: GET

Collection Variables

Collection variables are scoped to a specific collection and override global variables.

collection-variables.yaml
global:
  variables:
    TIMEOUT: "5000"      # Global level
    ENV: "production"

collection:
  variables:
    TIMEOUT: "10000"     # Overrides global
    COLLECTION_ID: "api_tests"
    
  requests:
    - name: "Test with overrides"
      variables:
        TIMEOUT: "30000"  # Overrides collection and global
        REQUEST_ID: "req_001"
      url: "${BASE_URL}/test"
      timeout: ${TIMEOUT}  # Uses 30000

Environment Variables

Access system environment variables using the ENV object.

env-variables.yaml
# Set environment variables
export API_KEY="your-secret-key"
export BASE_URL="https://api.staging.com"

# Reference in YAML
global:
  variables:
    API_TOKEN: "${API_KEY}"     # From environment
    API_BASE: "${BASE_URL}"     # From environment
    TIMEOUT: "5000"              # Static value

Variable Precedence

When variables are defined at multiple levels, curl-runner follows a specific precedence order.

Precedence Order (Highest to Lowest)

1Environment Variables${ENV.VAR_NAME}
2Collection Variablescollection.variables
3Global Variablesglobal.variables
variable-precedence.yaml
global:
  variables:
    TIMEOUT: "5000"      # Global level
    ENV: "production"

collection:
  variables:
    TIMEOUT: "10000"     # Overrides global
    COLLECTION_ID: "api_tests"
    
  requests:
    - name: "Test with overrides"
      variables:
        TIMEOUT: "30000"  # Overrides collection and global
        REQUEST_ID: "req_001"
      url: "${BASE_URL}/test"
      timeout: ${TIMEOUT}  # Uses 30000

Dynamic Variables

Create dynamic values using JavaScript expressions and built-in functions.

Built-in Functions

Date & Time

Date.now() - Current timestamp
new Date().toISOString() - ISO date
new Date().getTime() - Unix timestamp

Random Values

crypto.randomUUID() - UUID v4
Math.random() - Random number
Math.floor(Math.random() * 1000) - Random int
dynamic-variables.yaml
global:
  variables:
    # Dynamic timestamp
    TIMESTAMP: "${DATE:YYYY-MM-DD}"
    REQUEST_TIME: "${TIME:HH:mm:ss}"
    
    # UUID generation
    REQUEST_ID: "${UUID}"
    SESSION_ID: "${UUID:short}"
    
    # Random values
    RANDOM_NUM: "${RANDOM:1-1000}"
    RANDOM_STR: "${RANDOM:string:10}"

collection:
  requests:
    - name: "Request with dynamic values"
      url: "https://api.example.com/requests"
      headers:
        X-Request-ID: "${REQUEST_ID}"
        X-Timestamp: "${TIMESTAMP}"
        X-Session: "${SESSION_ID}"

Conditional Logic

Use JavaScript expressions to create conditional variables and environment-specific configurations.

conditional-variables.yaml
global:
  variables:
    # Environment-based variables
    BASE_URL: "${NODE_ENV:production:https://api.example.com:https://api-staging.example.com}"
    
    # Default value if environment variable not set
    API_TIMEOUT: "${API_TIMEOUT:5000}"
    
    # Multiple environment sources
    DB_HOST: "${DATABASE_HOST:${DB_HOST:localhost}}"

collection:
  requests:
    - name: "Environment aware request"
      url: "${BASE_URL}/data"
      timeout: ${API_TIMEOUT}

Complex Interpolation

Combine multiple variables and expressions to create complex, computed values.

complex-interpolation.yaml
global:
  variables:
    BASE_PATH: "/api/v1"
    RESOURCE: "users"
    
    # Computed from other variables
    FULL_ENDPOINT: "${BASE_URL}${BASE_PATH}/${RESOURCE}"
    
    # String manipulation
    UPPER_ENV: "${ENV:upper}"
    LOWER_RESOURCE: "${RESOURCE:lower}"

collection:
  requests:
    - name: "Using computed variables"
      url: "${FULL_ENDPOINT}"
      headers:
        X-Environment: "${UPPER_ENV}"
        X-Resource-Type: "${LOWER_RESOURCE}"

Best Practices

Best Practices

• Use descriptive variable names

• Define common values as variables

• Use environment variables for secrets

• Group related variables logically

• Document complex expressions

Avoid These Mistakes

• Hard-coding sensitive information

• Using overly complex expressions

• Creating circular references

• Overusing dynamic variables

• Ignoring variable naming conventions

Common Patterns

API Authentication

API Authentication Pattern
global:
  variables:
    API_KEY: ${ENV.API_KEY}
    AUTH_HEADER: "Bearer ${API_KEY}"
    
  defaults:
    headers:
      Authorization: ${AUTH_HEADER}

Environment-Specific URLs

Environment-Specific URLs
global:
  variables:
    ENVIRONMENT: ${ENV.NODE_ENV || 'development'}
    BASE_URL: ${ENVIRONMENT === 'production' 
      ? 'https://api.example.com' 
      : 'https://api-staging.example.com'}

Request Correlation IDs

Request Correlation IDs
global:
  variables:
    CORRELATION_ID: ${crypto.randomUUID()}
    
  defaults:
    headers:
      X-Correlation-ID: ${CORRELATION_ID}
      X-Request-Time: ${Date.now()}