2

Variables

Pavel Baksy edited this page 2026-01-13 16:59:00 +01:00

Table of Contents

• Variables
• What are Variables?
• Environments
• Creating Environments
• Step 1: Open Environments Dialog
• Step 2: Add Environment
• Step 3: Add Variables
• Step 4: Set Values
• Using Variables in Requests
• Variable Syntax
• Select Environment
• Visual Indicators
• Managing Variables
• Rename Variable
• Delete Variable
• Rename Environment
• Delete Environment
• Common Variable Patterns
• Script Integration
• Reading Variables (Preprocessing)
• Writing Variables (Postprocessing)
• Batch Updates
• Variable Scoping
• Best Practices
• Undefined Variables
• Environment Switching
• Advanced Topics
• Next Steps

Variables

Variables allow you to reuse values across multiple requests and switch between different environments (development, staging, production) with ease.

What are Variables?

Variables are placeholder values that you can reference in your requests using the {{variable_name}} syntax. When you send a request, Roster automatically replaces these placeholders with the actual values from your selected environment.

Example:

URL: {{base_url}}/users
Headers:
  Authorization: Bearer {{api_token}}

When sent with the "Production" environment:

URL: https://api.example.com/users
Headers:
  Authorization: Bearer prod-token-abc123

Environments

Environments are collections of variable values. Common environment names:

• Production - Live API credentials
• Staging - Pre-production testing
• Development - Local development server

Each project can have multiple environments, and each environment has its own set of variable values.

Creating Environments

Step 1: Open Environments Dialog

1. Select a project from the sidebar
2. Click the "Three-Dots" button near the project name
3. Select "Manage Environments"

Step 2: Add Environment

1. Click + button near Environments
2. Enter name (e.g., "Production", "Development")
3. Click "Add"

The environment appears as a new column in the table.

Step 3: Add Variables

1. Click the "+" button at the bottom of the variable list
2. Enter variable name (e.g., base_url)
3. Click "Add"

The variable appears as a new row in the table.

Step 4: Set Values

Click in the cells to enter values for each environment:

Variable	Production	Development
base_url	https://api.example.com	http://localhost:3000
timeout	30	60

Close Manage Environments table to save.

Using Variables in Requests

Variable Syntax

Use double curly braces: {{variable_name}}

Variables work in:

• URL: {{base_url}}/users
• Headers: Authorization: Bearer {{token}}
• Request Body: {"api_key": "{{api_key}}"}

Select Environment

1. Open a request tab
2. Use the environment dropdown (top of request panel)
3. Select environment (e.g., "Production")
4. All variables in the request will use values from this environment

Visual Indicators

Defined variables - Normal appearance

Undefined variables - Highlighted with a warning color

• Variable name exists in {{...}} syntax
• But not defined in current environment

Managing Variables

Rename Variable

1. Open Manage Environments dialog
2. Click on variable name
3. Edit the name

The variable is renamed across all environments automatically.

Delete Variable

1. Open Environments dialog
2. Click the x next to variable name
3. Confirm deletion

The variable is removed from all environments.

Rename Environment

1. Open Environments dialog
2. Click the edit icon on environment column header
3. Enter new name
4. Click "Save"

Delete Environment

1. Open Environments dialog
2. Click the trash icon on environment column header
3. Confirm deletion

All variable values for that environment are deleted.

Note: Each project must have at least one environment.

Common Variable Patterns

Common variables to define across environments:

• base_url - API base URL (e.g., https://api.example.com vs http://localhost:3000)
• api_version - API version (e.g., v2 vs v2-beta)
• timeout - Request timeout values
• env - Environment identifier for headers
• test_user_id - Test data IDs

Script Integration

Variables can be accessed and modified from Scripts:

Reading Variables (Preprocessing)

const baseUrl = roster.getVariable('base_url');
const apiKey = roster.getVariable('api_key');

console.log('Using base URL:', baseUrl);
request.headers['X-API-Key'] = apiKey;

Writing Variables (Postprocessing)

// Extract token from response and save for next request
const data = JSON.parse(response.body);
roster.setVariable('auth_token', data.access_token);
roster.setVariable('user_id', data.user_id);
console.log('Saved token for user:', data.user_id);

Batch Updates

// Update multiple variables at once
roster.setVariables({
    access_token: data.access_token,
    refresh_token: data.refresh_token,
    user_id: data.user.id,
    user_name: data.user.name
});

Scripts automatically update variables in the currently selected environment.

Variable Scoping

Project Level:

• Variables are defined at the project level
• All requests in the project can access these variables

Environment Level:

• Variable values are specific to each environment
• Switching environments switches all values at once

Not Global:

• Variables from one project cannot be used in another project
• Each project has its own isolated set of variables

Best Practices

• Keep environments consistent - All environments should have the same variable names with different values
• Use sensitive variables for secrets - Never store API keys, passwords, or tokens in regular variables (they're plain text). Use Sensitive-Variables instead

Undefined Variables

When {{variable_name}} is not defined in the current environment:

• Entry field is highlighted with warning color
• The literal text {{variable_name}} is sent in the request

To fix, add the variable in the Environments dialog.

Environment Switching

Use the environment dropdown to test the same request against different targets. For example, GET {{base_url}}/users will hit localhost:3000/users in Development or api.example.com/users in Production.

Advanced Topics

• Variables in JSON body - Use {{variable}} syntax. Remove quotes for numeric values
• Nested variables - Variables can reference other variables (e.g., {{base_url}}/{{api_version}})
• Script-created variables - Scripts can create variables with roster.setVariable()

Next Steps

• Sensitive-Variables - Store API keys and secrets securely
• Scripts - Automate variable management with JavaScript
• API-Reference - Complete API for working with variables