write-http-files

Files (3)

• SKILL.md
• environments.md · references/
• format-spec.md · references/

SKILL.md (first lines)

# Write HTTP request files

Produce `.http` (or `.rest`) files in the **HTTP Request in Editor** format — the
format the JetBrains HTTP Client and the VS Code REST Client extension run
directly from the editor. The goal is files a developer can open and execute
request-by-request without leaving their IDE, with variables and environments
factored out so the same file works across dev/staging/prod.

This format extends RFC 7230 with three things plain HTTP can't express: many
requests in one file, response-handler scripts, and `{{variable}}` substitution.

## When to use

- Creating a file to "test", "hit", or "call" an endpoint or API
- Converting a `curl` command, an OpenAPI/Swagger spec, or endpoint docs into runnable requests
- Building a collection of requests for a service (CRUD, auth flow, smoke tests)
- Adding variables, environments, or auth to existing `.http` files
- Chaining requests — log in, capture a token, use it in later requests

## Workflow

1. **Pick the filename.** Use `.http` (preferred) or `.rest`. Name it after the
   service or flow: `auth.http`, `users-api.http`, `smoke.http`.
2. **Factor out what varies.** Host, base path, ids, and secrets become
   `{{variables}}` from the start — never hardcode `https://api.staging...` or a
   bearer token inline. Decide where each variable lives (see Variables below).
3. **Write the requests**, separated by `###`. Order them so a human can run them
   top to bottom (auth first, then the calls that need the token).
4. **Wire up chaining** with response handlers (`> {% ... %}`) when a later
   request depends on an earlier response.
5. **If environments are needed**, create `http-client.env.json` for shared,
   non-secret values and `http-client.private.env.json` (gitignored) for secrets.
6. **Add a one-line comment** above each request saying what it does, so the file
   reads as living documentation.

## Essential format

A request is: an optional `###` separator, the request line, header lines, a
**blank line**, then the body. The blank line before the body is mandatory.

```http
### Get a user by id
GET https://{{host}}/api/users/{{userId}}
Accept: application/json

###

### Create a user
POST https://{{host}}/api/users
Content-Type: application/json

{
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}
```

Rules worth internalizing:

- **Request line**: `[METHOD] request-target [HTTP-version]`. Method defaults to
  `GET` and the version is optional, so `https://{{host}}/health` is a valid GET.
- **Separators**: `###` between requests; text after it on the same line is the
  request's title/comment. A leading/trailing `###` is fine.
- **Comments**: lines starting with `#` or `//`.
- **Body from a file**: `< ./payload.json` on its own line (after the blank line)
  instead of an inline body. File bodies are sent verbatim; inline bodies are
  trimmed.
- **Bodies are passthrough** — set `Content-Type` yourself; the format does not
  infer it from the body.

## Variables

Reference any variable as `{{name}}` in the request target, headers, or body.
Variables come from three places — prefer the lowest-friction one that fits:

- **In-file variables** for values reused within one file:
  `@host = api.example.com` near the top, then `{{host}}`. Good for a base URL or
  a shared id while iterating.
- **Environment files** for values that change per environment (dev/staging/prod).
  Non-secret values go in `http-client.env.json`; secrets go in
  `http-client.private.env.json` (must be gitignored). See
  [references/environments.md](references/environments.md).
- **Dynamic variables** for generated values: `{{$uuid}}`, `{{$timestamp}}`,
  `{{$randomInt}}`. Useful for idempotency keys and unique test data.

When secrets are involved, never inline them — route them through the private env
file and reference `{{token}}`. Call this out to the user so the secret doesn't
land in version control.

## Chaining requests

A response handler runs JavaScript after a response arrives; use it to stash a
value for later requests via `client.global.set`. Later requests read it as
`{{name}}`.

```http
### Log in and capture the token
POST https://{{host}}/auth/login
Content-Type: application/json

{ "user": "{{user}}", "password": "{{password}}" }

> {%
  client.global.set("token", response.body.token);
  client.test("got a token", () => client.assert(response.body.token));
%}

###

### Use the captured token
GET https://{{host}}/api/me
Authorization: Bearer {{token}}
```

The handler block starts with `>` and is enclosed in `{% %}`; it cannot contain
`%}` or `###`. To compare against a saved response, use `<> previous.200.json`.

## Reference material

The body above covers the common cases. Read these when a task needs more:

From Kotivskyi/skills, MIT.

More from Kotivskyi/skills