Using Variables

In Apidog, variables allow you to save and reuse values easily. Storing a value as a variable enables you to access it across various environments, requests, scripts, and test scenarios. Utilizing variables increases productivity and promotes teamwork among colleagues.

What are Variables?

A variable is a symbolic representation of data that allows you to retrieve a value without manually inputting it every time it's needed. This is beneficial for reusing the same values across different locations.

Example:
If you have the same token in multiple requests and anticipate changes, save the token as a variable named {{my_token}}. Use {{my_token}} in the request parameter value. When the token changes, updating the variable value updates it everywhere.

Variables can take effect in parameter values, bodies, URLs, or headers.

In Apidog's Tests module, variables can be used to pass data between requests.

Variable Scopes

Apidog supports variables in various scopes to adjust to different development, testing, and collaboration requirements.

Priority (from lowest to highest): Global < Module < Environment < Data < Local

When a variable with the same name is defined in different scopes, the value from the narrowest scope takes precedence.

Global Variables

Shared within Project: Accessible across an entire project. Useful for sharing data between endpoints (e.g., login token).

Shared within Team: Shared throughout the entire team across different projects (e.g., a token shared between a login project and a finance project).

NOTE

Permissions: To manage team variables, you need team admin permissions. Go to Team Resources > Variables.

Scripts: You can use pm.globals.set to update local values in scripts, but cannot change names or shared values.

Module Variables

Defined within a module. Importing from Postman "Collection variables" maps to Module variables.

Environment Variables

Tied to specific environments (Development, Testing, Production). Only the active environment's variables are effective.

Data Variables

Sourced from external CSV or JSON files in Test Scenarios or CLI. Values do not persist after the run.

Local Variables

Temporary variables confined to a single request or test scenario run. Disappear once completed.

TIP

Variables in Apidog are stored as strings. When saving objects or arrays, use JSON.stringify() to store and JSON.parse() to retrieve them.

Shared and Local Values

Each variable has two states:

Shared Value: Sychronized with Apidog servers and shared with the team.

Local Value: Stored LOCALLY in your browser or client cache. Not shared.

Best Practices:

Use Local Value for sensitive data (tokens, passwords) so they stay on your machine.

Leave Local Value empty to fall back to the Shared Value.

Click the link icon 🔗 to sync Local Value with Shared Value.

WARNING

Cleaning Apidog cache will delete Local Values.

Local Values do NOT migrate automatically when switching devices (use Environment Export/Import).

Using Variables in Apidog CLI

When running in the CLI, the Shared Value is used by default, whereas the Client uses the Local Value. This is a common cause for discrepancies between Client and CLI runs.

TIP

Learn more about the Apidog CLI.

Defining Variables

1. Environment Management (Preset)

Values for Global and Environment variables can be preset manually.

Click the Environment Management icon ≡.

Select Global Variables or a specific environment.

Add the variable name, shared value, and local value.

Click Save.

2. Extract Variables

Visually extract values from API responses into variables without writing code.

In the Run tab (Design Mode), go to Post Processors.

Select Extract Variable.

Configure extraction source (JSON, XML, Header, etc.) and JSONPath.

Send the request to execute and verify in the Console.

TIP

Learn more about Extract Variable.

3. Scripts

Use the pm object in Pre/Post-processors.

Syntax for set:

Storing Objects/Arrays:

TIP

Learn more about Script Syntax.

4. Database Operations

Connect to a database to retrieve data and set it as a variable.

Add Database Operation in Post Processors.

Configure database connection.

Enter SQL command (supports {{variable}}).

Set Extract Result To Variable.

TIP

Learn more about Database Operations.

Request Parameters

Use double curly braces {{variable}} in URL, parameters, headers, or body.

Example URL:
http://127.0.0.1/pet/findByStatus?status={{CurrentStatus}}

Example JSON Body:

{
    "status": "{{CurrentStatus}}",
    "quantity": {{TotalPet}}
}

WARNING

Strings: Add double quotes "" around the variable for strings (e.g., "{{name}}").

Numbers/Booleans: Do NOT add quotes (e.g., {{count}}).

Accessing Sub-elements

If a variable contains a JSON object/array, access properties via dot notation using JSONPath.

Object in {{user}}:

{ "id": 1, "name": "Jack" }

Request: {{user.name}}

Script: pm.variables.get("user.name")

Array in {{users}}:

[ { "name": "Jack" } ]

Request: {{users[0].name}}

Script: pm.variables.get("users[0].name")

Using Variables in Scripts

In scripts, use pm.*.get() instead of {{}}.

Logging:

Check the Console tab to see output.

Using Data Variables

In Test Scenarios, importing a CSV/JSON file creates "Data Variables". Use {{column_name}} to reference them. Each row in the file triggers a separate iteration.

TIP

Learn more about Data Driven Testing.

FAQ

Q: Can I use variables in Mocks?

No. Variables are resolved when a request is sent. Mocks are static definitions or run on the mock server without a client-side "sending" context in the same way.

Q: How do I get the base URL in a script?

Use pm.request.getBaseUrl().

Avoid pm.environment.get('BASE_URL') as it might be inaccurate for non-default server endpoints.

Using Variables

What are Variables?#

Variable Scopes#

Shared and Local Values#

Using Variables in Apidog CLI#

Defining Variables#

1. Environment Management (Preset)#

2. Extract Variables#

3. Scripts#

4. Database Operations#

Using Variables#

Request Parameters#

Accessing Sub-elements#

Using Variables in Scripts#

Using Data Variables#

FAQ#

What are Variables?

Variable Scopes

Shared and Local Values

Using Variables in Apidog CLI

Defining Variables

1. Environment Management (Preset)

2. Extract Variables

3. Scripts

4. Database Operations

Using Variables

Request Parameters

Accessing Sub-elements

Using Variables in Scripts

Using Data Variables

FAQ