Variables

Variables in RESTK let you parameterize your API requests so you can reuse values, switch environments, and keep secrets secure -- all without hardcoding anything. Use the {{variable}} syntax anywhere in your requests, and RESTK resolves the value at send time.

Variable Scopes

RESTK supports four variable scopes, plus runtime variables set by scripts.

Variables can also be marked as Secret (masked in UI, stored locally) regardless of scope.

---

Substitution Syntax

Use double curly braces {{variable_name}} to reference a variable. RESTK resolves variables in all request fields.

Where Variables Work

URL:

{{base_url}}/api/{{api_version}}/users/{{user_id}}

Headers:

Authorization: Bearer {{access_token}}
X-API-Key: {{api_key}}
Content-Type: {{content_type}}

Query Parameters:

?page={{page_number}}&limit={{page_size}}&sort={{sort_field}}

Request Body:

{
  "email": "{{test_email}}",
  "organization_id": "{{org_id}}",
  "api_key": "{{api_key}}"
}

Authentication Fields:

Token: {{access_token}}
Username: {{basic_auth_user}}
Password: {{basic_auth_password}}

---

Environment Variables

Environment variables are the most commonly used variable type. They let you define different values for each stage of your API (development, staging, production) and switch between them with one click.

Creating Environment Variables

Example: Multi-Environment Setup

Development:

base_url = http://localhost:3000
api_key  = dev_key_abc123
debug    = true

Staging:

base_url = https://api-staging.example.com
api_key  = staging_key_xyz789
debug    = true

Production:

base_url = https://api.example.com
api_key  = prod_key_secret456
debug    = false

Switch environments from the toolbar dropdown. All {{base_url}} references instantly resolve to the active environment's value.

---

Collection Variables

Collection variables are scoped to a single collection. They are useful for values shared across all requests within a collection but not relevant outside it.

When to Use Collection Variables

• Base paths specific to a service (e.g., /api/v2)
• Resource IDs used across multiple requests in the collection
• Tokens obtained during a login request and used by subsequent requests

Setting Collection Variables

In the UI:

In scripts:

// Set a collection variable
nova.collectionVariables.set("user_id", "12345");

// Get a collection variable
const userId = nova.collectionVariables.get("user_id");

---

Dynamic Variables

Dynamic variables generate a new value each time a request is sent. They are useful for timestamps, unique identifiers, and random test data.

Available Dynamic Variables

Usage Example

{
  "id": "{{$randomUUID}}",
  "created_at": "{{$isoDate}}",
  "request_id": "req_{{$timestamp}}"
}

---

Secret Variables

Secret variables provide secure storage for sensitive values like API keys, tokens, and passwords. Secret is a flag you can set on any variable, not a separate scope.

Creating Secret Variables

Characteristics

• Masked in UI: Values display as dots in the variable editor and auto-complete
• Stored locally: Secret values are stored on your device using the macOS Keychain and never synced
• Resolved at send time: The actual value is injected only when the request is sent

---

Setting Variables Programmatically

Use the nova.* scripting API to read, write, and manage variables in pre-scripts and post-scripts.

Core Methods

// Get a variable (searches all scopes by priority)
nova.variable.get("key")

// Set a runtime variable (not persisted after session)
nova.variable.set("key", "value")

// Check if a variable exists
nova.variable.has("key")

// Remove a variable
nova.variable.unset("key")

Scope-Specific Methods

// Environment variables (persisted)
nova.environment.get("base_url")
nova.environment.set("base_url", "https://api.example.com")

// Collection variables (persisted)
nova.collectionVariables.get("auth_token")
nova.collectionVariables.set("auth_token", data.token)

// Folder variables (persisted)
nova.folderVariables.get("folder_var")
nova.folderVariables.set("folder_var", "value")

// Request variables (persisted)
nova.requestVariables.get("request_var")
nova.requestVariables.set("request_var", "value")

Common Pattern: Extract and Store

// Post-script: Extract token from login response
const data = nova.response.json();

if (nova.response.status === 200 && data.access_token) {
  nova.environment.set("access_token", data.access_token);
  nova.environment.set("refresh_token", data.refresh_token);

  console.log("Tokens stored successfully");
}

---

Variable Precedence

When the same variable key exists in multiple scopes, RESTK resolves it using the following priority order (highest to lowest):

1. Runtime Variables       (set by nova.variable.set() — highest priority)
2. Request Variables
3. Folder Variables        (walks up the folder chain)
4. Collection Variables
5. Environment Variables   (lowest priority)

Example

Environment: base_url = "https://staging.example.com"
Collection:  base_url = "https://api-v2.example.com"

{{base_url}} resolves to https://api-v2.example.com because collection variables take precedence over environment variables.

---

Best Practices

1. Use environments for stage-specific values -- URLs, API keys, and feature flags that differ between dev, staging, and prod
2. Use collection variables for extracted data -- IDs and tokens obtained from responses within a collection
3. Mark sensitive values as Secret -- Never store API keys or passwords as default variables
4. Use descriptive names -- stripe_api_key is clearer than key1
5. Document your variables -- Add descriptions to environment variables so team members understand their purpose
6. Use scope-specific set methods -- Use nova.environment.set() instead of nova.variable.set() when you need values to persist

---

Next Steps