.http Files in Visual Studio

An .http file holds requests written as plain text, one after another, separated by ###. Visual Studio sends each one with a click and shows the response's status, headers and body, so you can test an API without leaving your project.

Journeyman · REST API · ASP.NET Core · Updated November 3, 2026

After this lesson you can

Write GET and POST requests in an .http file, with headers and a JSON body, and send them from Visual Studio
Read a response's status line, headers and body

Key takeaways

An .http file holds requests as plain text: the method and URL on the first line, then one header per line, with ### between requests.
@HostAddress = ... defines a variable once, and {{HostAddress}} puts it into each request.
To send a body, add a Content-Type header, then a blank line, then the body. Without the blank line, the body is read as more headers.
Read a response's status line first, then its headers, then its body.
201 Created with a Location header means the server saved the new item and says where to find it.

A request is just a text message, so the simplest way to test an API is to write that message yourself. An .http file does exactly that: requests written as plain text, kept in your project, sent with one click. Visual Studio, VS Code (with the REST Client extension) and JetBrains Rider all understand them.

Every new Web API project in Visual Studio comes with one, named after the project, such as NorthwindApi.http.

A GET request

@HostAddress = http://localhost:5179

GET {{HostAddress}}/api/categories/8
Accept: application/json

###

@HostAddress = ... defines a variable. {{HostAddress}} puts it in, so the address is written once. Use your own project's address: it's the http profile's applicationUrl in Properties/launchSettings.json.
The first line of the request is the method and the URL, exactly as the request message starts.
Header lines follow, one per line: Accept: application/json asks for JSON back.
### ends one request and starts the next. A file can hold as many as you like.

You'll build this categories API in Web APIs with Controllers. For now, read the requests and responses below; come back and send them once your API is running.

Start the API (Ctrl+F5), then click Send request above the GET line. The response opens beside the file:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "categoryId": 8,
  "categoryName": "Seafood",
  "description": "Seaweed and fish"
}

Reading the response

A response has the same two parts as a request:

Part	Here	Tells you
Status line	`HTTP/1.1 200 OK`	Whether it worked: the status code `200` and its name
Headers	`Content-Type: application/json`	About the body: here, that it's JSON
Body	`{ "categoryId": 8, ... }`	The data itself

Check the status first. A 200 with the data you expected means it worked; a 404 means the address points at nothing; a 400 means the request had a mistake in it; a 500 means the server broke. The next topic covers them all.

A POST request with a body

To send data, add a Content-Type header saying what the body is, then a blank line, then the body:

POST {{HostAddress}}/api/categories
Content-Type: application/json

{
  "categoryName": "Snacks",
  "description": "Chips, nuts and pretzels"
}

###

The blank line matters: it's where the headers end and the body begins, as in every HTTP message. Without it, the body would be read as more headers.

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: http://localhost:5179/api/categories/9

{
  "categoryId": 9,
  "categoryName": "Snacks",
  "description": "Chips, nuts and pretzels"
}

201 Created and a Location header pointing at the new category: the server saved it, gave it id 9, and says where to find it.

Why keep requests in a file?

They're saved. Tomorrow, the same requests are there to send again, in order.
They're in the project. Commit the .http file with your code, and everyone on the team can test the API the same way.
They're readable. The file is the HTTP messages themselves, so it doubles as documentation of your API.

Tools such as Postman and Insomnia do the same job with a window of buttons and tabs, and add extras such as automated test runs. The ideas are identical: method, URL, headers, body.

Check yourself

2 questions to try on the lesson page.

So what

An .http file is the HTTP conversation written down. Write the request, send it, read the status, headers and body, and you can test every endpoint of your API without writing a single line of client code.

Key terms

Cheat sheets