.http files are the rare developer convention that just works: API requests as plain text,
next to the code, runnable from VS Code, JetBrains IDEs, or a dedicated client.
The trouble never comes from the format. It comes six months later, when those files are
scattered across five repositories, and nobody remembers which one has the working login
request. This guide covers the conventions that keep .http files findable — and the three
realistic ways to work with them once they cross repo boundaries.
New to the format itself? Start with the .http file guide — this post assumes you're already writing them.
Why .http files end up scattered
The format's biggest strength causes the sprawl: because requests live next to the code they exercise, every service accumulates its own. That's correct — a request belongs with its API. But it means your "collection" is now the union of files across every repo you touch, and no editor window shows you that union. The fix is not to centralize the files. It's to adopt conventions so each repo's files are predictable, then pick a cross-repo strategy.
A folder convention that keeps requests findable
Pick one location per repo and never deviate. Two patterns work well:
/http/at the repo root — one folder, all request files. Best for services with a single API surface.- Next to the module (
src/orders/orders.http) — best for monoliths where APIs are owned by different teams.
Whichever you choose, write it down in the repo's README. The convention matters more than
the choice: "requests are always in /http/" is what makes a five-repo search trivial.
Naming and structuring the files themselves
- One file per API area, not per request:
orders.http,auth.http,webhooks.http. A file with eight related requests separated by###is easier to scan than eight files. - Name requests with comments above each
###block so the file reads as a table of contents. - Declare
@variablesat the top of the file — one place to change the host or version.
@baseUrl = https://api.example.dev/v2
### Create order
POST {{baseUrl}}/orders
Content-Type: application/json
{ "sku": "KRV-1", "qty": 2 }
### Get order by id
GET {{baseUrl}}/orders/1042
How do you handle environments without leaking secrets?
Keep values that differ per environment (hosts, tokens) out of the .http file and in
dotenv files beside it — dev.env, staging.env — and let your client inject them into
{{placeholders}}. Two rules keep this safe:
- Commit the
.httpfiles. Git-ignore any.envthat holds real credentials. Commit asample.envwith dummy values instead, so new teammates see the expected shape. - Never inline a production token "just for one test". Files that diff like code also leak like code.
Three ways to work across repos
| Strategy | Cost | Cross-repo view | Where it breaks |
|---|---|---|---|
| Editor extension per repo | Free | None — one window per repo | Multi-service debugging |
| Central "requests" repo | Free | One repo to rule them all | Drifts from the code it describes |
| Workspace app over the files | Paid (Karve) | All repos, one window | Windows-only, REST-only today |
1. Stay in your editor
VS Code REST Client or the JetBrains HTTP Client run the file you have open. If your work is mostly one repo at a time, this is genuinely enough — and it's free. The ceiling: no unified view, no shared history, and environment handling is per-window. (Honest comparison: Karve vs VS Code REST Client.)
2. A central requests repo
Some teams collect all .http files into one dedicated repository. You get a single
checkout with everything — but the files now live away from the code they test, and they
drift: the API changes, the request repo doesn't. It also turns every request edit into a
cross-repo commit. Workable for small, stable API surfaces; painful past that.
3. A workspace over your files
The third option keeps files where they belong and adds a layer above them. This is what
Karve does: it gathers .http/.rest files from any folder or repo into virtual
collections — the files never move — and adds the workspace parts the format lacks:
per-file .env environment switching, tabs, and a searchable history of every request and
response. Files stay plain text, keep diffing in Git, and stay editable in any IDE.
Full disclosure: Karve is our product; it's Windows-native, one-time-purchase, and
REST-only today (roadmap).
Quick checklist
- One agreed folder per repo (
/http/), documented in the README. - One file per API area;
###blocks with comment titles. @variablesat the top; environment values in dotenv files, not inline.- Real secrets git-ignored; a
sample.envcommitted. - Convert strays into the format as you find them — the free cURL → .http, OpenAPI → .http, and HAR → .http converters run entirely in your browser.
- Pick your cross-repo strategy deliberately — editor-only is fine until it isn't.
Choosing a client to sit on top of all this? See our honest roundup of Postman alternatives for Windows.