unkn0wn-root/resterm v1.12.0 on GitHub

v1.12.0

Breaking change (pre-request scripts, `@apply`, and `@patch` only):

helpers such as {{$uuid}} in values written by a script are now sent as plain text. This changed because script values often come from a server response, and the server could inject a helper such as {{$randomString(4096)}}, which Resterm would then fill in and send. Helpers written directly in a .http or .rest file work as before.

To get values from variables and helpers in a script string, use the new vars.interpolate. It was added for exactly this.

Migration: helpers in script values

// Before: sent a new UUID in 1.11.0. Now sends as plain text.
request.setHeader("X-Request-Id", "{{$uuid}}");

// Now: sends a new UUID.
request.setHeader("X-Request-Id", vars.interpolate("{{$uuid}}"));

This covers setURL, setHeader, addHeader, setQueryParam, and setBody in JavaScript and RestermScript, and url, headers, query, body, and auth returned by @apply or @patch:

# @apply {headers: {"X-Request-Id": vars.interpolate("{{$uuid}}")}}

A helper in settings returned by @apply or @patch now fails the request, the same way a variable did in 1.11.0:

@apply settings.timeout: contains template text. Write it in a @setting line

To use the same generated value in a script and in the request, nothing changes. Declare it with # @request id {{$uuid}} and read it with vars.get("id").

vars.interpolate

vars.interpolate(text) replaces each {{name}} with the value of vars.get(name). Helpers such as {{$uuid}} generate a new value each time they appear. It works in JavaScript, RestermScript, and @apply.

# @file base https://api.example.com
# @file token env:GITHUB_TOKEN

### Repos
# @name repos
# @script pre-request
> vars.set("userId", "42");
> request.setURL(vars.interpolate("{{base}}/users/{{userId}}/repos"));
> request.setHeader("Authorization", vars.interpolate("Bearer {{token}}"));
GET https://api.example.com

It reads the same variables as vars.get, including values set earlier in the script. @const values and OS variables without an env:NAME mapping are not available.
Placeholders inside an inserted value are not expanded again.
A missing variable, a {{= ... }} expression, an empty {{ }}, or a placeholder without a closing }} throws an error.
Do not pass response text to vars.interpolate. It could contain {{token}} and read a secret. Store it with vars.set and insert it with {{name}} instead.

To read a variable named interpolate in RestermScript, use vars.get("interpolate").

Warnings for placeholders sent as text

When a pre-request script writes a value that still contains {{name}}, {{$helper}}, or {{= ... }}, Resterm sends it as written and shows a warning with the file and line of the call:

api.http:7: Script sends {{token}} in header Authorization as written. Use vars.get("token").
api.http:8: Script sends {{$uuid}} in header X-Request-Id as written. Use vars.interpolate("{{$uuid}}").

This works for JavaScript and RestermScript.
The warning appears in the status bar, in Explain, and under the request in resterm run. JSON reports list them in warnings on each result.
A helper name Resterm does not know, such as {{$uuuid}}, gets Check the helper name, or use vars.get("$uuuid").
@apply and @patch already warned about {{name}} and {{= ... }} in their strings. They now warn about helpers such as {{$uuid}} too. Strings passed to vars.interpolate do not get a warning.

Editor completion for vars

Typing vars. or vars.global. now lists methods such as get, set, and interpolate. This works in JavaScript blocks, {{= ... }} expressions, and RestermScript directives such as @assert, @capture, and @apply.

require is suggested only in RestermScript.
Expressions and directives cannot change variables, so set and delete are not suggested there.
Nothing is suggested inside JavaScript strings or comments.

See Interpolating text and RestermScript vars for details.

Fixed

JavaScript errors now point to the line and column in your request file or script file. In 1.11.0, they showed the line inside the script block, such as <eval>:2:7(6):

error[script]: Error: boom
--> api.http:7:9