Modern ASP.NET Core API templates can include an .http file for trying the generated endpoints.
It is easy to treat that file as disposable scaffolding. It becomes much more valuable when it is
maintained as the smallest executable description of the API paths developers use every day.
This is not a replacement for automated tests. It is a fast, reviewable workflow for exploration, reproduction, support, and manual verification.
Start with one realistic file
Assume a Minimal API exposes health and order endpoints. Create requests/orders.http:
@baseUrl = https://localhost:7042
GET {{baseUrl}}/health
Accept: application/json
###
POST {{baseUrl}}/orders
Content-Type: application/json
Authorization: Bearer {{token}}
{
"sku": "KARVE-001",
"quantity": 2
}
###
GET {{baseUrl}}/orders/1
Accept: application/json
Authorization: Bearer {{token}}
The example captures three facts a teammate otherwise has to reconstruct: the actual paths, the minimum headers, and a valid body shape.
Match the local development URL
Local HTTPS ports vary by project and profile. Read the active profile in
Properties/launchSettings.json, or use the URL printed when the app starts. A connection failure
usually means the API is not running, the wrong launch profile is active, or the file contains an
old port—not that the request syntax is broken.
Keep a safe local default in the file if the team shares one. Put staging and production hosts in environments instead of editing the request line before every run.
Keep credentials outside the request
Commit this:
Authorization: Bearer {{token}}
Do not commit the substituted token. Visual Studio can read .env values through its $dotenv
helper, JetBrains uses public/private JSON environment files, and the VS Code extension uses its own
environment settings. Karve selects a dotenv file directly and resolves ordinary {{token}}
references.
Whichever client the team chooses, ignore the real secret container and commit only a redacted example documenting required names.
Organize by bounded workflow
A useful structure for a larger solution is:
requests/
health.http
auth.http
orders.http
catalog.http
local.env.example
Avoid one generated mega-file. A bounded file is easier to scan, produces smaller diffs, and can contain the happy path plus the two or three failures developers actually reproduce.
Name requests with comments when the runner supports it, but keep the method line and separator clear enough that the file remains usable without those annotations.
Review request changes like code
An .http change can reveal an API contract change before a client library is regenerated:
-POST {{baseUrl}}/orders
+POST {{baseUrl}}/v2/orders
Content-Type: application/json
{
- "quantity": 2
+ "units": 2
}
Review whether the route, header, or payload change matches the server implementation. Keep example values harmless and deterministic. If an example requires a real customer ID or production token, it does not belong in the repository.
Use the right level of testing
Request files are good for:
- trying an endpoint while implementing it
- reproducing a bug from a support report
- documenting an authentication handshake
- checking a local or staging deployment manually
- giving a reviewer a runnable example
They do not replace assertions, repeatable setup, isolation, or CI. If a behavior must block a release, write an automated test. JetBrains and other tools can add scripts or CLI execution, but that is a deliberate expansion beyond the portable REST examples Karve runs.
Work across several ASP.NET Core repos
Visual Studio works well for the API in the open solution. Microservice work often needs requests
from several solutions at once. Karve can collect the existing files into virtual folders while
leaving every path inside its original repository. You get one native Windows view, a selected
.env environment, and searchable request/response history without creating a proprietary
collection.
See API client workflows for .NET developers for the product view,
or browse the reviewed ASP.NET Core .http examples.
Primary reference
Microsoft Learn: Use .http files in Visual Studio 2022.