Ian Wilson

What http files are and how they work

At their core, .http files are plain text files containing one or more HTTP requests. Each request is written in a format that closely resembles raw HTTP, making them easy to read and easy to reason about.

A single request in a .http file typically consists of:

• A HTTP method and URL
• Optional headers
• Optional body content
• Optional metadata such as variables or scripts (depending on the client)

A minimal example:

GET https://api.example.com/users
Accept: application/json

POST https://api.example.com/users
Content-Type: application/json

{
   "name": "Alice", 
   "email": "alice@example.com" 
}

The syntax is close to the wire format of HTTP, which makes it intuitive for anyone familiar with APIs. Multiple requests in a single file One of the strengths of .http files is that you can define multiple requests in a single document. This makes them ideal for:

• Documenting an entire API
• Creating a workflow of dependent calls
• Testing sequences such as authentication → data retrieval → cleanup

Requests are separated using a special delimiter line: ###

GET https://api.example.com/login
###

GET https://api.example.com/profile 
Authorization: Bearer {{token}} 
###

Environment Variables

Environment variables are one of the most powerful features of .http files. They allow you to:

• Switch between dev, test, and production environments
• Avoid hard coding secrets
• Reuse values across multiple requests
• Parameterise URLs, headers, and bodies

Variables are typically defined in a companion file such as:

• rest-client.env.json (VS Code REST Client)

Example: Single environment

@baseUrl = https://api.example.com
@token = abcd1234

GET {{baseUrl}}/users 
Authorization: Bearer {{token}}

Example Multiple environments

{
  "dev": {
    "baseUrl": "http://localhost:3000",
    "token": "dev-token"
  },
  "prod": {
    "baseUrl": "https://api.example.com",
    "token": "prod-token"
  }
}

Then in the .http file:

GET {{baseUrl}}/users 
Authorization: Bearer {{token}}

Switching environments can be done in a single click.

Why This Matters

The combination of readable syntax, multiple request support, comments, and environment variables makes .http files a compelling alternative to heavyweight API testing tools. They encourage:

• Repeatability — requests live in version control
• Transparency — everything is plain text
• Speed — no UI navigation, just run the request
• Collaboration — teammates can run the exact same calls

They’re especially powerful for developers who want API testing to feel as natural as writing code.