Skip to main content
Environments in Yasumu allow you to define different configurations for various deployment stages (development, staging, production) or testing scenarios. Each environment contains variables and secrets that can be referenced in your API requests.

​
What are environments?

Environments provide a way to:

Switch contexts

Quickly switch between different API endpoints, credentials, and configurations.

Secure secrets

Store sensitive data like API keys and tokens separately from regular variables.

Share configs

Commit environment templates to Git while keeping secrets local.

Test scenarios

Create multiple environments for different testing scenarios and data sets.

​
Environment structure

Environments are stored as .ysl files in the yasumu/environment/ directory: 
@environment

metadata {
  id: "c10t47a2kufpq46wt9oomc4d"
  name: "Production"
}

variables [
  {
    key: "API_URL"
    value: "https://api.example.com"
    enabled: true
  },
  {
    key: "API_VERSION"
    value: "v2"
    enabled: true
  },
  {
    key: "TIMEOUT"
    value: "5000"
    enabled: true
  },
]

secrets [
  {
    key: "API_KEY"
    value: "sk_live_abc123def456"
    enabled: true
  },
  {
    key: "USER_TOKEN"
    value: "eyJhbGciOiJIUzI1NiIs..."
    enabled: true
  },
]

​
Variables vs. secrets

Variables are for non-sensitive configuration values:
  • API endpoints and URLs
  • Port numbers and timeouts
  • Feature flags and settings
  • User IDs and test data
  • Version identifiers
Variables are safe to commit to version control.
variables [
  {
    key: "API_URL"
    value: "https://api.dev.example.com"
    enabled: true
  }
]

​
Creating environments

Create environments using the Environment Manager API:
import { Workspace } from '@yasumu/core';

// Create a new environment
const env = await workspace.environments.create({
  name: 'Development',
});

// Add variables
env.variables.set('API_URL', 'https://api.dev.example.com');
env.variables.set('API_VERSION', 'v1');
env.variables.set('DEBUG', 'true');

// Add secrets
env.secrets.set('API_KEY', 'sk_test_abc123');
env.secrets.set('DB_PASSWORD', 'secure-password');

console.log('Environment created:', env.name);

​
Managing environments

// Get all environments
const environments = await workspace.environments.list();

environments.forEach(env => {
  console.log(`${env.name} (${env.id})`);
});

​
Working with variables

The Environment class provides a convenient API for managing variables and secrets: 
const env = await workspace.environments.get('env-id');

// Set variables
env.variables.set('API_URL', 'https://api.example.com');
env.variables.set('PORT', '3000');
env.variables.set('DEBUG', 'true');

// Set secrets
env.secrets.set('API_KEY', 'sk_live_abc123');
env.secrets.set('DB_PASSWORD', 'password123');

​
Variable interpolation

Reference environment variables in your REST requests using double curly braces: 
@rest

request {
  url: "{{API_URL}}/users/{{userId}}"
  headers: [
    {
      key: "Authorization"
      value: "Bearer {{API_KEY}}"
      enabled: true
    },
    {
      key: "X-API-Version"
      value: "{{API_VERSION}}"
      enabled: true
    }
  ]
}

​
Interpolation syntax

Yasumu supports three interpolation patterns:
Looks up in variables first, then secrets:
url: "{{API_URL}}"
# Checks variables.API_URL, then secrets.API_URL

​
Programmatic interpolation

You can also interpolate strings programmatically: 
const env = await workspace.environments.getActiveEnvironment();

if (env) {
  const url = env.interpolate('{{API_URL}}/users/{{userId}}');
  console.log(url); // https://api.example.com/users/12345
  
  const auth = env.interpolate('Bearer {{secrets.API_KEY}}');
  console.log(auth); // Bearer sk_live_abc123
}

​
Enabling/disabling variables

Variables and secrets can be temporarily disabled without deleting them: 
variables [
  {
    key: "API_URL"
    value: "https://api.example.com"
    enabled: true  # Active
  },
  {
    key: "OLD_API_URL"
    value: "https://old-api.example.com"
    enabled: false  # Disabled but preserved
  },
]
Programmatically: 
// Get variable
const variable = env.variables.get('API_URL');

if (variable) {
  // Check if enabled
  if (variable.enabled) {
    console.log('Variable is active');
  }
  
  // Disable (you'll need to update the entire variable)
  env.variables.set('API_URL', {
    ...variable,
    enabled: false,
  });
}

​
Secrets management best practices

1

Create environment template

Commit the environment file with empty secret values:
secrets [
  {
    key: "API_KEY"
    value: ""  # Empty in repository
    enabled: true
  }
]
2

Document required secrets

Add a README or comments explaining which secrets are needed:
## Required Secrets

- `API_KEY`: Production API key from dashboard
- `DB_PASSWORD`: Database connection password
3

Populate locally

Each developer fills in secrets locally:
env.secrets.set('API_KEY', 'actual-key-value');
env.secrets.set('DB_PASSWORD', 'actual-password');
4

Add to .gitignore (optional)

If you want to prevent accidental commits:
# Ignore environment files with secrets
yasumu/environment/production.ysl
Never commit files with populated secret values. Always use empty strings for secrets in version control.

​
Environment use cases

Development

Local API endpoints, test credentials, and debug flags.
variables [
  { key: "API_URL" value: "http://localhost:3000" enabled: true }
  { key: "DEBUG" value: "true" enabled: true }
]

Staging

Staging server URLs and test account credentials.
variables [
  { key: "API_URL" value: "https://staging.example.com" enabled: true }
  { key: "DEBUG" value: "false" enabled: true }
]

Production

Production endpoints and live credentials (secrets only).
variables [
  { key: "API_URL" value: "https://api.example.com" enabled: true }
]
secrets [
  { key: "API_KEY" value: "" enabled: true }
]

Testing

Test data, mock endpoints, and test account credentials.
variables [
  { key: "API_URL" value: "https://mock.example.com" enabled: true }
  { key: "TEST_USER_ID" value: "test-123" enabled: true }
]

​
Next steps

REST API Testing

Use environment variables in REST requests

Scripting

Access environment variables in scripts

Schema Language

Learn about environment .ysl format

Workspaces

Understand workspace structure

Build docs developers (and LLMs) love

Get started for freeTalk to us