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 can be beneficial for reusing the same values across different locations. By using variables, your requests become more adaptable and easier to understand by hiding the specific details.

For instance, when you have the same token in multiple requests and anticipate changes to it in the future, you can save the token as a variable named {{my_token}} and utilize it in your requests by putting {{my_token}} in the request param value. Each time the token changes, the variable value will update it throughout your requests, wherever the variable is used.

This concept can be applied to any repeated data in your requests. The stored value in a variable will be included wherever the variable is referenced when your requests are executed. Varables could take effect in param values, in bodies, in URLs or in headers.

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

Variable scopes

Apidog offers support for variables in various scopes, allowing you to adjust your processes to different development, testing, and collaboration requirements. The scopes in Apidog correspond to the contexts in which your requests operate, and each scope serves a unique purpose.

Arranged from the widest to the narrowest scope, these include: global, environment, data, and local variables.

• Global variables permit the sharing of data across requests, scripts, and environments within a project. They are accessible project-wide. Due to their broad scope, global variables are ideal for testing and initial experimenting. As your project progresses, consider utilizing more specific scopes.

• Environment variables allow you to target your work to specific environments, such as local development, testing, or production. When switching environments, the values of the environment variables for the current environment take effect. Only one environment can be active at a time.

• Data variables are sourced from external CSV or JSON files to define datasets in test scenarios or in the Apidog CLI. These variables have transient values that do not persist after a request or collection run.

• Local variables are temporary variables confined to a single request or test scenario run and disappear once the run is completed. Local variables are useful for temporarily overriding other variable scopes without maintaining the value after execution.

When a variable with the same name is defined in different scopes, the value from the narrower scope will take precedence. In other words, the priority of variable effectiveness is global < environment < data < local.

For instance, if there is a global variable named "id" and a local variable also named "id", the value of the local variable will be utilized when the request is executed.

:::tip[]
Variables in Apidog are stored as strings. When saving objects or arrays, make sure to use JSON.stringify() to convert them to strings before storing, and use JSON.parse() when retrieving them.
:::

Initial and current values

Each variable has an Initial value and Current value.

• Initial value represents the value set within the element (environment or globals) where the variable is established. This value is synchronized with Apidog's servers and is shared with your team when you share that specific element. Setting an initial value can be beneficial for collaborating with teammates. However, please be aware that the data within an initial value will be shared with others and potentially be accessible to the public.

• Current value is utilized when sending a request. These are local values that are not synchronized with Postman's servers. Changes made to a current value are not permanently saved in the original shared API documentations, environment, or globals.

Current value is only saved locally, making it suitable for storing sensitive data such as passwords, tokens, etc. This data is not synchronized with other team members, allowing each individual to utilize their own current value seperately and securely.

If you do not need to use a personal Current Value, you can leave the Current Value empty. In this case, the Current value will follow the Initial value. However, if you input a value in the Current value field, the variable will no longer use the Initial value.

You can also click on the link icon 🔗 next to the Current value to rebind the Current value to the Initial Value.

:::tip[]

• Since the current values are only stored locally, using cleaning software to clean the Apidog file cache will cause the current values to be deleted. So please be cautious.
• When changing devices, the current value does not automatically migrate with your account. You can achieve migration by using the export-import environment feature.
• If you are using Apidog Web, the current value is stored in your browser data.
  :::

Using variables in Apidog CLI

After setting up your Test Scenario in the Apidog client, you can run this scenario using the Apidog CLI on any machine.

It's important to note that when running in the client, the current value of variables is used, while in the CLI, the initial value of variables is used. If the results of running in the client and the CLI differ, this is often the reason.

:::highlight purple
Learn more about the Apidog CLI.
:::

Defining variables

There are several ways to define variables, depending on where your variable values come from. You can preset variable values in the Environment Management popup, extract variables or perform database operations in the pre/post-processors, or set variable values using custom scripts.

Preset variable values in Environment Management

You can preset values for global variables and environment variables in the "Environment Management" popup by following these steps:

:::tip[]
Variables' Initial Value can only be set in the environment popup. When using processors and scripts, you can only set the Current value of variables but not the Initial value.
:::

Add an "Extract Variable" operation

Apidog supports visually extracting values from the API response and saving them as variables. Follow these steps:

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

http://127.0.0.1/pet/findByStatus?status=available

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

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

[
  {
    id: 1,
    name: "jack",
  },
];

var name = pm.environment.get("variable");

console.log(pm.variables.get("variable_key"));