Variables

A variable is a named value. You write it into a request as {{name}}, and Postguy replaces it when the request is sent. Use variables for base URLs, tokens, ids and anything that changes between environments.

{{baseUrl}}/users/{{userId}}

Syntax rules:

• Names are matched exactly as written, including case. Spaces inside the braces are part of the name. Write {{baseUrl}}, not {{ baseUrl }}.
• You can use a variable in the URL, query and path-variable rows, header names and values, every body mode, and the fields of authorization.
• A value can contain other variables. They expand recursively to a depth of 10. A name that refers back to itself, directly or through a chain, is left as literal text and flagged as unresolved.
• A name that no scope defines is left as literal text. For example, {{missing}} is sent as {{missing}}. If the unresolved name is in the URL's host, the send fails with an error instead.
• A variable whose row is disabled, or whose name is empty, does not exist.
• {{% starts a shortcode, not a variable.

Precedence

When the same name is defined in several scopes, the highest rank wins.

globals      baseUrl = https://api.example.com
environment  baseUrl = http://localhost:8080     <- wins over globals
request URL  {{baseUrl}}/health  ->  http://localhost:8080/health

The folders and the collection come from the request's position in the tree. See Collections.

Scripts can read and write several scopes. See Scripts and tests and the scripting API. Folder variables and the data row are read-only to scripts.

Environments and globals

An environment is a named set of variables, for example Local, Staging or Production. Only one environment is active at a time.

Choose the active environment from the selector at the right end of the tab strip, or pick No environment. The active environment applies to every request in the workspace.

• Create an environment with + Create new environment at the bottom of the selector, or from the sidebar.
• The ... menu in the editor has Duplicate, Export and Delete. Each environment has a colour dot.
• The editor tab has a table with an enabled checkbox, name, value and an optional description. You can search, drag to reorder, and add a row by typing in the empty row at the end. Changes save automatically.
• Globals is a single set of variables for the whole workspace. Open it with the Globals button in the bottom bar. It has the same editor and the lowest precedence.
• The Vars button next to the selector opens a quick look at the active environment, the globals and the current collection's variables. Secret values are masked until you reveal them. Click a row to copy its value.
• Collections and folders hold their own variables in their detail tabs.

Chips and autocomplete

Fields that accept variables tint each {{name}}. These fields are:

• The URL bar.
• The key and value cells of the Query Params, Path Variables, Headers, form-data and x-www-form-urlencoded tables.
• The raw and GraphQL body editors.

Hover a chip to see its name, scope and value. Secret values stay masked until you hold Cmd/Ctrl.

Type {{ in the URL field to open a list of the variables you can reach. It shows up to eight at a time and filters as you type.

Secret variables

Mark a row Secret in an environment, the globals, a collection or a folder. A secret variable resolves like any other, with these differences:

• The value is stored in .postguy/secrets.json in the workspace, never in the collection or environment file. The file is mode 0600 on Unix.
• The value is masked in the editor. Use Reveal secrets, or hold Cmd/Ctrl, to see it.
• Wherever Postguy echoes a request, each occurrence of a secret's value is replaced with •, one per character and at most 16. This covers the Console, the request saved in History, script failure messages and the recorded URL and headers.
• Environment and globals exports leave secret values out unless you explicitly include them. See Import and export.
• Code snippets keep {{variables}} unresolved, so they do not contain the value.

A secret row whose value is missing from the secrets file resolves to an empty string.

Dynamic variables

Names that start with $ are generated when the request is sent. Each occurrence gets a new value.

{
  "id": "{{$guid}}",
  "createdAt": "{{$isoTimestamp}}",
  "email": "{{$randomEmail}}",
  "quantity": {{$randomInt}}
}

More are available for names, people, places, internet values, dates, finance, text and files. Their values come from word lists written for Postguy. An unknown $name is left as literal text. See the full list in Dynamic variables.

Shortcodes

A shortcode puts a computed value, or the content of a collection asset, into a request body. Write it between {{% and %}}.

{{% base64(file('lib/a.jpg')) %}}

Grammar:

• A call is name(arg, ...). Names are lowercase letters and digits.
• file and text take exactly one quoted path. The other functions take exactly one argument: a quoted string or another call.
• Strings use '...' or "...". Escape a backslash, a single quote or a double quote with a backslash.
• Whitespace is allowed around the call, so {{%base64(file('a'))%}} also works.
• {{variables}} inside a string argument resolve first. So {{% text('{{dir}}/note.txt') %}} reads from the folder that dir names.

Limits:

Where shortcodes apply

Shortcodes expand first. The result then goes through normal {{variable}} resolution.

They need a stored request, because assets belong to a collection. Assets live in <workspace>/assets/<collection id>/. Manage them in the collection's Assets tab.

Errors and colours:

• An invalid shortcode, a missing asset or a binary result without base64(...) stops the send with an error that names the problem.
• The editor marks that shortcode red and shows the reason.
• Valid shortcodes are blue.

An asset is capped at 100 MiB. An import is capped at 2 GiB or 10,000 files.

{
  "name": "avatar",
  "data": "{{% base64(file('images/avatar.png')) %}}",
  "checksum": "{{% sha256(text('images/avatar.txt')) %}}"
}