Variables

Variables are used for avoiding unnecessary data duplication in requests or for providing an easy way of switching between environments. They can be used inside request line, header fields, request body or in variable definitions. Each variable is represented by a case-sensitive identifier surrounded by double curly braces.

@foo=bar
GET https://httpbin.org/anything?q={{foo}}

Variable Scope

The scope is the current context of execution in which variables are "visible" or can be referenced. If a variable or expression is not in the current scope, it will not be available for use.

• Environment Variables: All Variables provided with provideVariables Hook (e.g. dotenv)

• File Global Variables: Variables defined in Region without name or request

• Request Variables: Variables defined in current region

TIP

You could expand the visiable scope using @import, @ref and @forceRef.

You can also explicitly define variables as global by adding them to the global object in the script.

GET /anything?foo=bar

{{
  $global.foo=response.parsedBody.args.foo;
}}

###
GET /anything?bar={{$global.foo}}

Inline Variables

Inline Variables can be easily created with the following scheme. Variable Substitution is supported.

@foo=bar
@fooExtended={{foo}}_Extendend
GET https://httpbin.org/anything?q={{fooExtended}}

Inline Variables in global scripts are set for each request in the file

@host=https://httpbin.org
###
GET /post

GET /post

For variables, a distinction is made between fixed and lazy variables. The fixed variables are evaluated directly at definition (request result would query ?foo=foobar).

@bar=bar
@foo=foo{{bar}}
###
GET https://httpbin.org/anything?foo={{foo}}

###
# @name result
@bar=bar2
GET https://httpbin.org/anything?foo={{foo}}

Lazy variables are only evaluated before a request or NodeJS execution (request result would query ?foo=foobar2). .

@bar=bar
@foo:=foo{{bar}}
###
GET https://httpbin.org/anything?foo={{foo}}

###
# @name=result
@bar=bar2
GET https://httpbin.org/anything?foo={{foo}}

TIP

If a required variable is not yet defined, it will also be set lazy

Import Variables

The variables are also imported from other files using @import. Only Variables in File Global Scope are imported.

# @import ./variablesInit.http
GET https://httpbin.org/anything?q={{fooExtended}}

To import request Variables, you can also reference (@ref) named responses (@name) from other files.

import.http

# @import ./name.http
# @ref json
POST https://httpbin.org/anything
{{json.slideshow.author}}

name.http

# @name json
GET https://httpbin.org/json

###
# @ref json
POST https://httpbin.org/anything
{{json.slideshow.author}}

Variable Substitution in Request

Before the request is sent, all variables in the request (request line, headers, request body) are replaced with the value of the variable.

TIP

If the replacement is not desired, this can be prevented using \{\{...\}\}. This is replaced by {{...}}

POST https://httpbin.org/anything
{
  "template": "My \{\{someVerb\}\} template!!"
}

NodeJs Script

All entries of the form {{...}} are interpreted as NodeJS Javascript which returns exactly one value. Since all variables can be easily accessed on the global scope, this allows for simple substitution.

@foo = test

GET https://www.httpbin.org/anything?bar={{foo}}&q={{new Date().toString()}}

TIP

It is possible to create more complex scripts, but this is not recommended and you should use a separate script block instead.

Host

If the url starts with / and a variable host is defined the URL of this host will be pre pended

@host=https://httpbin.org
###
GET /anything?q=1
GET /anything?q=2

Input, Password and QuickPick

Dynamic Variable Resolution with input field, password field or quick pick is supported.

@query = {{$input input app? $value: foo}}
GET https://httpbin.org/json?q={{query}}

@query = {{$password input app? $value: foo}}
GET https://httpbin.org/json?q={{query}}

@query = {{$pick select app? $value: foo,bar}}

GET https://httpbin.org/anything?q={{query}}

TIP

If only a one-time input is desired, the renewed query can be avoided using -askonce.

@query = {{$input-askonce input app? $value: foo}}
GET https://httpbin.org/json?q={{query}}

@query = {{$pick-askonce select app? $value: foo,bar}}

GET https://httpbin.org/anything?q={{query}}

OAuth2 / OpenID Connect

The following Open ID Connect flows are supported.

• Authentication (or Basic) Flow with or without PKCE (grant_type = authorization_code)
• Implicit (or Hybrid) Flow (grant_type = implicit)
• Resource Owner Password Grant (grant_type = password)
• Client Credentials Grant (grant_type = client_credentials)
• Device Authorization Grant (grant_type = device_code)

GET /secured_service
Authorization: openid {{grant_type}} {{prefix}}

TIP

If no grant_type is provided client_credentials flow is used. If no prefix is provided value oauth2 is used.

To configure the flow, the following variables must be specified

variable	description	authorization_code	implicit	password	client_credentials	device_code
{{prefix}}_tokenEndpoint	Token Endpoint URI	x	x	x	x	x
{{prefix}}_clientId	OAuth 2.0 Client Identifier	x	x	x	x	x
{{prefix}}_clientSecret	OAuth 2.0 Client Secret	x	x	x	x	-
{{prefix}}_authorizationEndpoint	Authorization Endpoint URI	x	x	-	-	-
{{prefix}}_redirectUri	Redirection URI to which the response is sent	x (default: localhost:3000)	x (default: localhost:3000)	-	-	-
{{prefix}}_scope	Scope	x (default: openid)	x (default: openid)	x	x	x
{{prefix}}_resource	Resource Indicators (RFC8707)	x	x	x	x	x
{{prefix}}_responseType	response type of auth server	-	x (default: code)	-	-	-
{{prefix}}_audience	audience	x	x	-	-	-
{{prefix}}_username	username	-	-	x	-	-
{{prefix}}_password	password	-	-	x	-	-
{{prefix}}_keepAlive	AccessToken is automatically renewed in the background, if request_token is provided (default: false)	x	-	x	x	-
{{prefix}}_useAuthorizationHeader	use Authorization Header for request (default: true)	x	x	x	x	-
{{prefix}}_usePkce	enable PKCE support	x (default: false)	-	-	-	-
{{prefix}}_deviceCodeEndpoint	Device Code Endpoint URI	-	-	-	-	x
{{prefix}}_interceptRequest	function used to modify request	x	x	x	x	x

WARNING

To get the code from the Open ID server, a http server is started for the Authorization Flow and Implicit Flow on port of the redirection Uri (default Port 3000). The server is stopped after receiving the code (delay 2 minutes). You need to configure your OpenId Provider to allow redirectUri as valid redirection uri

TIP

The http server started for the Authorization Flow and Implicit Flow listens on the port of _redirectUri. You can configure a different port for the server to listen to with variable oauth2_serverPort. If the port localhost:8000 is mapped to host https://port-8000.external-domain in a reverse proxy, you can set variable _redirectUri as https://port-8000.external-domain/callback and set variable oauth2_serverPort to 8000.

@keycloakHost = http://127.0.0.1:8080
@local_tokenEndpoint = {{keycloakHost}}/auth/realms/local/protocol/openid-connect/token
@local_clientId = httpyac
@local_clientSecret = 936DA01F-9ABD-4D9D-80C7-02AF85C822A8
@local_scope = openid profile

GET /secured_service HTTP/1.1
Authorization: openid client_credentials local

@job_clientId=c003a37f-024f-462a-b36d-b001be4cd24a
@job_clientSecret=32a39620-32b3-4307-9aa1-511e3d7f48a8
@job_tokenEndpoint=https://api-con.arbeitsagentur.de/oauth/gettoken_cc
@job_useAuthorizationHeader=false

###

GET https://api-con.arbeitsagentur.de/prod/jobboerse/jobsuche-service/pc/v2/app/jobs?FCT.AKTUALITAET=100&FCT.ANGEBOTSART=ARBEIT
Authorization: oauth2 client_credentials job

It is possible to convert the generated token into a token of another realm using Token Exchange

GET /secured_service HTTP/1.1
Authorization: openid client_credentials local token_exchange realm_auth

Examples

• .env The following examples use the following values as variables.

oauth2_clientId=httpyac
oauth2_clientSecret=dBBg5uRBE2eZbvMVbGD40DTdEL6wTGak

oauth2_tokenEndpoint=http://localhost:8080/realms/master/protocol/openid-connect/token
oauth2_authorizationEndpoint=http://localhost:8080/realms/master/protocol/openid-connect/auth
oauth2_deviceCodeEndpoint=http://localhost:8080/realms/master/protocol/openid-connect/auth/device
oauth2_username=john
oauth2_password=doe

pkce_clientId=httpyac_pkce
pkce_clientSecret=3KZc1jK1WTLunuHZD3AKTZWtWwn4JwFV
pkce_usePkce=true

device_clientId=httpyac
device_clientSecret=dBBg5uRBE2eZbvMVbGD40DTdEL6wTGak
device_deviceCodeEndpoint=http://localhost:8080/realms/master/protocol/openid-connect/auth/device

• Authorization Code Flow

GET https://httpbin.org/anything
Authorization: oauth2 code

• Authorization Code Flow with PKCE

GET https://httpbin.org/anything
Authorization: oauth2 code pkce

• Implicit Flow

GET https://httpbin.org/anything
Authorization: oauth2 implicit

• Client Credentials Flow

GET https://httpbin.org/anything
Authorization: openid

• Device Code Flow

GET https://httpbin.org/anything
Authorization: oauth2 device_code device

• Password Flow

GET https://httpbin.org/anything
Authorization: oauth2 password

AWS Signature v4

AWS Signature v4 authenticates requests to AWS services.

@accessId = doe
@accessKey = 12345678
@token = token
@region = eu-central-1
@service = cognito-idp

###
GET https://cognito-idp.eu-central-1.amazonaws.com
Authorization: AWS {{accessId}} {{accessKey}} token:{{token}} region:{{region}} service:{{service}}
GET https://cognito-idp.eu-central-1.amazonaws.com
Authorization: AWS {{accessId}} {{accessKey}} token:{{token}}
GET https://cognito-idp.eu-central-1.amazonaws.com
Authorization: AWS {{accessId}} {{accessKey}}

SSL Client Certificate

To use SSL Client Certificates, the clientCertificates setting must be set. This contains the certificate to be used for each host. For each host either the certificate/ key or pfx/ passphrase must be maintained.

• cert: Path of public x509 certificate
• key: Path of private key
• pfx: Path of PKCS #12 or PFX certificate
• passphrase: Optional passphrase for the certificate if required

{
  "clientCertificates": {
    "example.com": {
      "cert": "./client.crt",
      "key": "./client.key"
    },
    "client.badssl.com": {
      "pfx": "./badssl.com-client.p12",
      "passphrase": "badssl.com"
    }
  }
}

GET https://client.badssl.com/

path should be absolute or relative to workspace root

It is also possible to attach the certificate using (X-)ClientCert header. The header will be removed.

GET https://client.badssl.com/
ClientCert: pfx: ./badssl.com-client.p12 passphrase: badssl.com
GET https://client.badssl.com/
X-ClientCert: pfx: ./badssl.com-client.p12 passphrase: badssl.com

Basic Authentication

A support method is provided for using Basic Authentication. Just specify the username and password separated by spaces and the base64 encoding will be applied automatically

@user = doe
@password = 12345678
###
GET /basic-auth/{{user}}/{{password}}
Authorization: Basic {{user}} {{password}}

If the username or password contains spaces, a : can be used alternatively.

@user = john doe
@password = 12345678

###
GET /basic-auth/{{user}}/{{password}}
Authorization: Basic {{user}}:{{password}}

Digest Authentication

A support method is provided for using Digest Authentication. Just specify the username and password separated by spaces and the digest access authentication will be applied automatically

@host = https://httpbin.org
@user = doe
@password = 12345678

GET /digest-auth/auth/{{user}}/{{password}}
Authorization: Digest {{user}} {{password}}

If the username or password contains spaces, a : can be used alternatively.

@host = https://httpbin.org
@user = john doe
@password = 12345678

GET /digest-auth/auth/{{user.replace(' ', '+')}}/{{password}}
Authorization: Digest {{user}}:{{password}}

Intellij Dynamic Variables

Intellij dynamic variables are supported.

Name	Description
$uuid	generates a universally unique identifier (UUID-v4)
$timestamp	generates the current UNIX timestamp
$randomInt	generates a random integer between 0 and 1000.

GET https://httpbin.org/anything
  ?$timestamp={{$timestamp}}
  &$uuid={{$uuid}}
  &$random.uuid={{$random.uuid}}
  &$randomInt={{$randomInt}}
  &$isoTimestamp={{$isoTimestamp}}
  &$random.integer={{$random.integer(2, 8)}}
  &$random.float={{$random.float(2, 8)}}
  &$random.alphabetic={{$random.alphabetic(50)}}
  &$random.email={{$random.email}}
  &$random.hexadecimal={{$random.hexadecimal(3)}}

Rest Client Dynamic Variables

Rest Client dynamic variables are partially supported.

Name	Description
$guid	generates a universally unique identifier (UUID-v4)
$randomInt min max	generates a random integer between min and max.
$timestamp [offset option]	generates the current UNIX timestamp
$datetime rfc1123|iso8601|"custom format"|'custom format' [offset option]	generates a datetime string in either ISO8601, RFC1123 or a custom display format
$localDatetime rfc1123|iso8601|"custom format"|'custom format' [offset option]	generates a local datetime string in either ISO8601, RFC1123 or a custom display format
$processEnv [key]	lookup key in process.env
$dotenv [key]	lookup key in dotenv variables

GET /anything?q={{$guid}}

GET /anything?q={{$randomInt 100 200}}

GET /anything?q={{$randomInt -100 100}}

GET /anything?q={{$randomInt -100 -50}}

GET /anything?q={{$randomInt -50 -100}}

GET /anything?q={{$timestamp}}

GET /anything?q={{$timestamp 2 h}}

GET /anything?q={{$datetime rfc1123}}

GET /anything?q={{$datetime rfc1123 2 h}}

GET /anything?q={{$datetime iso8601}}

GET /anything?q={{$datetime iso8601 2 h}}

GET /anything?q={{$datetime "DD.MM.YYYY"}}

GET /anything?q={{$datetime "DD.MM.YYYY" 2 d}}

GET /anything?q={{$datetime 'DD.MM.YYYY'}}

GET /anything?q={{$datetime 'DD.MM.YYYY' 3 d}}

GET /anything?q={{$localDatetime rfc1123}}

GET /anything?q={{$localDatetime rfc1123 2 h}}

GET /anything?q={{$localDatetime iso8601}}

GET /anything?q={{$localDatetime iso8601 2 h}}

GET /anything?q={{$localDatetime "DD.MM.YYYY HH:mm"}}

GET /anything?q={{$datetime "DD.MM.YYYY HH:mm" 2 d}}

GET /anything?q={{$datetime 'DD.MM.YYYY HH:mm'}}

GET /anything?q={{$datetime 'DD.MM.YYYY HH:mm' 3 d}}

GET /anything?q={{$processEnv USER2}}
GET /anything?q={{process.env.USER2}}

XPath Query

Variables can be extracted from XML using XPath query.

$xpath(:<variableName>) <xpath>

If no variableName is provided and the last response is of Mimetype XML, the last response.body is used

### foo
GET /xml

###
# @ref foo
GET /anything?q={{$xpath:foo //@author}}

You could provide XPath Namespaces using @xpath_ns

@xpath_ns hello=http://learnwebservices.com/services/hello

POST https://apps.learnwebservices.com/services/hello
Content-Type: application/xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header/>
   <soapenv:Body>
       <HelloRequest xmlns="http://learnwebservices.com/services/hello">
          <Name>John Doe</Name>
       </HelloRequest>
   </soapenv:Body>
</soapenv:Envelope>


?? xpath //hello:Message == Hello John Doe!