Postcards

Document APIs with executable example requests.

Postcard format

Each Postcard (any file with the extension .pcard) contains the definition of one example request:

// comments start with two slashes

GET https://api.example.com/items
? search = R&D projects
? tag = first
? tag = second
Accept: application/json

Blank lines and comment lines are ignored while reading request metadata. The first meaningful line contains the HTTP method and URL. A line beginning with ? adds a query parameter; spaces around the first = are ignored, and the name and value are URL-encoded automatically. Repeated names, declaration order, and empty values are preserved. Other meaningful lines are request headers.

Comments may also follow request data when separated from it by whitespace:

GET https://api.example.com/items // Fetch all items
Accept: application/json // Prefer a JSON response

Query parameters may instead remain in the request URL. Inline parameters are treated as already encoded and are left unchanged. Both styles can be combined:

GET https://api.example.com/items?version=2
? search = R&D projects

Request bodies

For methods such as POST, put the body after a blank line following the query parameters and headers:

POST https://{{host}}/projects
Authorization: Bearer {{auth_token}}
Content-Type: application/json

{
  "name": "{{project_name}}",
  "active": true
}

The first non-comment line after a blank line that is not another valid query parameter or header begins the body. This means blank lines can still separate request metadata. Everything from the beginning of the body to the end of the file is sent as authored, including indentation, blank lines, and text that looks like a Postcards comment.

Bodies are raw text: Postcards does not infer a content type, serialize JSON, or escape substituted variable values. Variables and secrets are resolved by textual substitution, so values must be valid for the body format in which they are used. GET and HEAD bodies are not supported by the Fetch runtime and are reported as errors.

Variables and contexts

Requests may require context variables in URLs, friendly query values, header values, and bodies:

GET https://{{host}}/projects
? status = {{status}}
X-Environment: {{environment}}

Variable names are case-sensitive and use letters, digits, and underscores, starting with a letter or underscore. A request containing variables must use a selected context; .pcard files do not define fallback values.

Variables embedded in the request URL are substituted as written before Fetch normalizes the URL. Variables used in friendly ? name = value lines are substituted before the query value is URL-encoded.

Contexts are .pctx files named after the context they provide. For example, prod.pctx defines the prod context:

// Production values
host = api.example.com
status = active
environment = production
secret auth_token

The secret declaration records that a context provides a variable without putting its value in the file. The request uses it like any other variable:

Authorization: Bearer {{auth_token}}

When sending a request whose required secret has no stored value, Postcards asks for it using a masked input. The value is saved in VS Code's encrypted secret storage, scoped to the workspace folder, context, and variable name; it is not written to the repository or synchronized to other machines. Run Postcards: Forget Secret for Context to choose one stored secret to remove, or to remove all secrets for the selected context, and be prompted again when they are next needed.

Secret-ness belongs to a context binding. For example, dev.pctx may use a committed test value while prod.pctx declares the same variable as secret. Within merged layers of one context, however, a variable cannot be both a literal value and a secret.

Postcards looks for .pctx files beside the request and then in each parent directory up to the containing VS Code workspace folder. Files with the same name are merged from the workspace root toward the request, so the nearest file overrides variables from broader parent contexts.

Run Postcards: Select Context or use the Postcards status-bar item to choose a context. The selection is remembered for that workspace folder. Previewing and sending are blocked if a required variable is absent from the selected context. Context loading and request sending require a trusted workspace.

Preview and send requests

Run Postcards: Preview Request from the Command Palette or choose Preview Request directly above the request line. The parsed request appears in a read-only Postcards Result editor beside the request file. Previewing does not send a network request or retrieve and prompt for secret values; declared secrets appear as REDACTED.

Valid .pcard files show Send Request and Preview Request actions directly above the request line. Invalid request syntax is underlined in the editor and reported in VS Code's Problems panel as you type.

Send a request

Choose Send Request above a valid request or run Postcards: Send Request from the Command Palette. Postcards sends the parsed method, URL, query parameters, headers, and body, then displays the response status, headers, and body in the read-only Postcards Result editor beside the request. The outgoing request is shown above the response, preceded by the source filename and the context used. It includes all authored headers and the default User-Agent: vscode/rbme.postcards header. An authored User-Agent overrides that default. Requests time out after 30 seconds. Request bodies are shown after the outgoing headers. Response bodies are limited to 5 MiB; larger bodies are truncated and marked in the Result editor.

Secret values are replaced with REDACTED in the displayed request. Postcards also scrubs raw and commonly URL-encoded occurrences from response content, redirect URLs, and request errors before displaying them.

The request section shows the URL and headers from the normalized Fetch Request that Postcards sends. When Fetch follows a redirect, Postcards adds a redirect section showing the original and final URLs. Intermediate redirect hops and transport-generated headers are not currently shown.