Testing APIs with .http Files

A .http file is a plain-text file that describes API requests you can run straight from your editor. No app, no account, no cloud sync. The request lives next to your code, commits to git, and reviews in a pull request. For day-to-day API testing, it is the lightest setup there is.

What Is a .http File?#

A .http file (sometimes .rest) holds one or more HTTP requests in a simple text format. Editors and CLIs that understand the format let you run each request and see the response inline. It is the format behind the VS Code REST Client extension, IntelliJ IDEA's built-in HTTP client, and the httpyac CLI.

The Syntax#

A request is a method and URL, optional headers, a blank line, then an optional body:

GET https://api.example.com/users/1
Authorization: Bearer {{token}}

GET https://api.example.com/users/1
Authorization: Bearer {{token}}

A request with a JSON body:

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

{
  "name": "Ada"
}

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

{
  "name": "Ada"
}

Put several requests in one file, separated by ###:

### List users
GET https://api.example.com/users

### Create a user
POST https://api.example.com/users
Content-Type: application/json

{ "name": "Ada" }

### List users
GET https://api.example.com/users

### Create a user
POST https://api.example.com/users
Content-Type: application/json

{ "name": "Ada" }

Variables and Environments#

Use {{variable}} placeholders so you are not hardcoding a base URL or token:

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

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

Each tool has its own way to set these per environment (a dev vs prod base URL, for example): VS Code REST Client uses environment settings, IntelliJ uses an http-client.env.json file, and httpyac reads variables and .env files. The point is the same: one file, many environments, no secrets baked into the request.

Tools That Run .http Files#

• VS Code REST Client: A "Send Request" link appears above each request; the response opens in a side panel
• IntelliJ IDEA HTTP Client: Built in; run a request from the gutter, with response history
• httpyac: A CLI (httpyac send file.http) plus editor extensions, also supporting GraphQL, gRPC, and WebSocket

Running in CI#

Because httpyac and IntelliJ's client can assert on the response and run from the command line, a .http file can double as a lightweight API test in CI. Keep the requests in the repo, run them in a pipeline step, and fail the build when an endpoint returns the wrong status or shape.

Limitations to Know#

• No rich GUI. Great for developers, less friendly for non-technical teammates than a full client.
• Format differences. The core syntax is shared, but variables, assertions, and scripting differ between REST Client, IntelliJ, and httpyac, so files are not always 100% portable.
• Not a monitor. Running a request on demand tells you it works now, not that it still works at 3am.

Best Practices#

1. Commit your .http files. The whole benefit is that requests live in the repo and review like code.
2. Never hardcode secrets. Use {{variables}} and per-environment config, not literal tokens.
3. Group by resource or flow. One file per API area keeps things findable.
4. Promote the important ones to monitors. A request worth testing repeatedly is worth watching in production.

Conclusion#

.http files give developers a fast, version-controlled way to test APIs without leaving the editor or signing into anything. They cover building, sending, and even asserting on requests. What they do not do is keep watching once you close the file.

That last step is where ObserveOne fits. Take the request you just wrote and point ObserveOne's API checks at it: the same method, headers, and body, plus assertions on status and response time, run on a schedule from multiple regions, alerting you when the endpoint breaks.