Developer Syntax Reference

A complete specifications manual for authoring .http requests, utilizing environments, script VMs, and the stateful local SQLite DB engine in RawRequest.

Annotations & Directives

RawRequest implements an extended JetBrains/VS Code compatible .http format. Request blocks are separated by ###, and directives utilize @ prefixes to manage state, chaining, and mock server routing.

Directive Syntax / Pattern Description
@name @name nameOfRequest Identifies a request block. Mandatory for references in @depends or variables chaining.
@depends @depends nameOfRequest Specifies a single named dependency. That request executes first and can populate variables or response data used by this request.
@env @env.profile.var = value Defines a environment-specific variable, resolved when the corresponding profile is activated.
@load @load duration=30s users=50 rampUp=5s rps=200 Configures a request as a high-concurrency performance benchmark. Common keys include users, duration, rampUp, rps, and failureRateThreshold.
@timeout @timeout 5000 Defines request network timeout in milliseconds. Defaults to system settings.
@no-history @no-history Flag to instruct the system NEVER to log the responses or bodies to disk (useful for sensitive API keys or PHI).
@mock @mock Flags a request as a local API mock endpoint definition rather than an outgoing client request. Stops play buttons from appearing.
@mockinit @mockinit Declares a one-shot startup script. Executed exactly once when the mock server starts, perfect for DB schema setup.

Variables & Secrets Resolvers

RawRequest resolves dynamic variable placeholders at compile time before outgoing client network requests or mock routes are processed.

1. Interpolation Precedence

Placeholder interpolation utilizes the double-brace syntax {{variableName}}. Variables resolve according to the following strict order of priority:

  1. Local Route Variables: Path parameters extracted from active mock endpoints (e.g. {{id}} parsed from /users/:id).
  2. Environment Profiles: Variables defined with @env.[activeProfile].varName = value.
  3. Global File-Level Variables: Variables defined globally at the top of the file as @varName = value.
  4. System Environment Variables: Prefixed with env. (e.g. {{env.USER}}) referencing local OS environment strings.
  5. Secure Vault Secrets: Securely stored credentials resolved from OS Keychain/Keyring services.

2. Encrypted Secrets Vault

To store sensitive credentials without committing them to git, use the system keyring resolver:

Authorization: Bearer {{secret:myApiKey}}
Security Note: RawRequest desktop GUI integrates with macOS Keychain, Windows Credential Manager, and Linux Secret Service. Values remain encrypted and are never written to the local project text files.

3. Request Chaining (Chained Context)

If a request uses @depends authRequest, you can dynamically reference parts of its completed response directly in the headers or body of subsequent blocks:

### Chained Request
GET {{baseUrl}}/profile
Authorization: Bearer {{authRequest.response.body.token}}

Pre & Post Script VM Sandbox

RawRequest embeds an isolated ECMA5 JavaScript runtime (Goja VM) to support scripting before sending a request (< { ... }) or after receiving a response (> { ... }).

1. The Script Block Syntax

  • Pre-Request Block (< { ... }): Executes before network dispatching. Can modify request properties or initialize mock route actions.
  • Post-Response Block (> { ... }): Executes after response reception. Used to execute test assertions and save session states.

2. Runtime Sandbox Schema

Inside the JS VM enclosure, the following global structures are automatically populated:

Object Key / Property Type Description
`request`
(Available in Pre & Mock scripts)		 request.method string HTTP Method (e.g. "GET", "POST")
request.path string Matched endpoint path (e.g. "/users/42")
request.body string Raw incoming request body string
request.params object Parsed route wildcards key-map (e.g. { id: "42" })
request.query object Query params key-map (e.g. { search: "Alice" })
request.headers object Headers key-map from incoming HTTP request
`response`
(Available in Post & Mock scripts)		 response.status number HTTP response status integer (e.g. 200)
response.body string | object Body string or structured JSON payload returned by routes
response.headers object Headers key-map for outgoing or received values
response.json object | array | undefined Parsed JSON body when the response body contains valid JSON.

3. Predefined Global Methods

  • assert(condition: boolean, message?: string): Evaluates truthiness. If false, throws an assertion error, stopping chains and logging failures.
  • setVar(name: string, value: any): Binds a variable in the active session, making it available to subsequent chained requests in the file.
  • console.log(...args: any[]): Prints formatted logs. Routed directly to Wails Console Drawer log frames or CLI outputs.

Stateful SQLite Database Driver API

Mock scripts (decorated with @mock or @mockinit) can leverage our embedded persistent SQLite client via the global db object.

Best Practice: Use the @mockinit block to define database tables once at startup. This keeps your regular route pre-scripts dry and performant.

1. SQLite Driver Methods Catalog

db.exec(sql: string, ...params: any[]): DbExecResult

Executes write or schema queries (e.g. CREATE, INSERT, UPDATE, DELETE) using prepared statements to prevent SQL injections.

Returns DbExecResult Object:
  • lastInsertId (number): The auto-incremented primary key of the last inserted row.
  • rowsAffected (number): The count of database rows modified by the command.
const res = db.exec("INSERT INTO logs (level, msg) VALUES (?, ?)", "info", "App started");
console.log("Logged ID:", res.lastInsertId);

db.query(sql: string, ...params: any[]): object[]

Executes a read query (e.g. SELECT). Returns a full array of objects representing matching rows.

const users = db.query("SELECT * FROM users ORDER BY id DESC");
response.body = users; // Automatically serialized as JSON!

db.get(sql: string, ...params: any[]): object | null

Convenience read query that returns the first matched row as an object, or null if no rows match.

const user = db.get("SELECT * FROM users WHERE email = ?", email);
if (!user) {
  response.status = 404;
  response.body = { error: "Not found" };
}

Model Context Protocol stdio Specification

RawRequest implements a direct zero-port Model Context Protocol (MCP) server over standard input/output (stdio), allowing AI assistants to query your workspace.

Exposed stdio AI Tools

  • list_files: Discovers all .http documents recursively inside the registered AI workspace.
  • list_requests: Dissects the requests, parameters, named blocks, timeouts, and chains inside a target file.
  • run_request: Runs a specific named request in the file, automatically resolving dependencies, environment variables, pre/post scripts, and secure vault credentials. Returns timing, status, headers, and body.
  • list_environments: Inspects all environment keys defined in the file.
  • set_variable: Injects temporary runtime variable mappings into the active execution context.
  • create_request: Adds a new named HTTP request to a target .http file.
  • update_request: Modifies an existing named request while preserving surrounding file content.
  • save_variable: Persists a global or environment-scoped variable into the target .http file.

CLI Command Reference

Compile RawRequest to run headless in terminal shell processes, scheduling suites, or triggering stress tests in pipelines.

# Run specific request
rawrequest run api.http -n login

# Target prod environment with custom variables
rawrequest run api.http -n getProfile -e prod -V "apiKey=custom_token"

# Stream body output only (ideal for jq parsing)
rawrequest run api.http -n getProfile -o body | jq .

# Trigger load test benchmark on named request
rawrequest load api.http -n stressTest --users 100 --duration 1m --fail-rate 0.02