HTTP requests

An HTTP request is a method, a URL, optional query parameters, path variables, headers and a body. It also has authorization, scripts, tests and per-request settings.

This page covers the builder tab, what Postguy sends, and how the response is shown and recorded.

Request tabs: Params, Authorization, Headers, Body, Scripts, Tests, Settings and Docs.

• Authorization: Authorization
• Scripts and tests: Scripts and tests

Send a request

The top row has the method menu, the URL field and the Send button.

• Methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. Any other method is rejected when the request is built.
• Send: click Send, press Enter in the URL field, or press Cmd/Ctrl+Enter. The split button's menu has Send and Download. It also saves the body when the response arrives (see Save a response).
• Cancel: while a request runs, Send becomes Cancel and a progress line runs over the URL bar. A cancel reports the phase it stopped in.
• Save: press Cmd/Ctrl+S, or click Save. A dot beside it marks unsaved changes. Sending uses the current draft, so you do not have to save first.
• cURL paste: paste a command that starts with curl into the URL field to import it into the request.
• No scheme: a URL without a scheme is sent as http://<url>.

Sending uses the active environment from the selector at the end of the tab strip. See Variables.

URL, query params and path variables

The URL and the Params tab stay in sync:

• Type ?a=1 in the URL to add a row.
• Edit a row to update the URL.
• The Path Variables table lists every :name segment in the URL path.

{{baseUrl}}/users/:userId/orders?status=open

When you send the request, Postguy does this:

1. Resolves {{variables}} in the URL. An unresolved variable in the host is an error. Elsewhere it stays literal.
2. Replaces :name segments with the value in the Path Variables table. A row with an empty value leaves :name in place.
3. Merges enabled query rows into the URL. A row replaces a pair with the same key. Pairs that exist only in the URL are kept. Disabled rows are not sent.
4. Converts the host to ASCII (IDNA). Values of enabled query rows and path variables are percent-encoded.

Turn off Encode URL automatically in the request Settings tab to skip percent-encoding of query and path values.

Bulk Edit turns the table into key: value lines.

Headers

The Headers tab has:

• Editable rows. Disabled rows are not sent.
• Bulk Edit.
• A Presets menu with four built-in sets: JSON, XML, Form URL Encoded and No cache. Custom presets are not available yet.

Header names and values may contain {{variables}}.

A name with a space, a colon or a control character is refused before sending. So is a value with a line break.

Rows you add go on the wire first, in table order. Then Postguy adds the automatic headers below. It skips any header whose name you already set (names are compared case-insensitively).

Tick Show auto-generated headers in the Headers tab to see the generated rows. They are never saved with the request.

Body

Pick the mode from the Body type menu on the Body tab. Switching mode keeps the other modes' content until you save. Only the active mode is stored.

Raw languages set a Content-Type when you have not set one yourself:

Beautify re-indents a JSON raw body.

form-data rows. A text row can have its own content type. A file row sends the file's name and application/octet-stream, unless the row has a content type.

GraphQL.

• Variables must be a JSON object. Empty or invalid text is sent as {}, and a warning goes to the Console.
• Operation name is sent only when it is not empty.
• Refresh schema runs an introspection query against the URL and lists the types in the tab.

Variables and shortcodes. {{variables}} resolve in every body mode. Shortcodes such as {{% base64(file('lib/a.jpg')) %}} expand in raw, urlencoded, form-data text and GraphQL bodies.

Files and the working directory

Binary bodies and form-data file rows read a file from disk.

• Relative paths resolve against the working directory. It is <workspace>/files unless you set another in Settings › General.
• Files outside the working directory are refused, unless Read files outside the working directory is on.
• A file is capped at 100 MiB.

A file row or binary path that is exactly {{% file('name') %}} reads name from the collection's assets instead of the disk. Any other shortcode in a file path is an error.

Per-request settings

The Settings tab holds the values below. A new request gets the defaults.

Redirect and cookie behaviour is described in Cookies, proxy and certificates.

How global settings combine

Global values live in Settings. For each send, Postguy combines them with the request's values:

The send pipeline

Every send runs the same twelve steps. This is true from the app, the runner or a tool.

If Settings › Disable scripts is on, steps 2 and 11 are skipped and a warning is written to the Console.

Response viewer

The response pane has the tabs Body, Cookies, Headers and Test Results. After a test has run, the last one shows as Test Results (passed/total).

The status badge, size and time sit on the right. Hover them to see:

• The HTTP version and redirect count.
• The header and body sizes, and the wire size if the body was compressed.
• The connect, wait (TTFB), download and total times.

Save a response

Save Response (or Save body to file in the ... menu) writes the decoded body to <workspace>/files/response-<tab id>.bin. The path shows in the status bar.

Send and Download does the same after the send completes.

History and Console

Each send is recorded, unless it comes from the collection runner.

• History. The sidebar's History section lists sends newest first, with method, URL and time.
  • An entry stores the request as sent (secret values masked), the status, duration and size.
  • The newest 5,000 entries are kept.
  • Open or delete an entry from its context menu.
  • Response bodies are stored under .postguy/responses/ only when Save response bodies in history is on in Settings › General.
• Console. Open it from the bottom bar. It logs each request as METHOD URL -> status · ms · bytes.
  • It shows expandable request headers, response headers and body (a body is cut at 1 MiB), the effective proxy, and any warnings.
  • Secret values are masked.
  • It keeps up to 5,000 entries for 24 hours.

See Workspace for where these files live.