API Testing in VS Code Using `api.http` (REST Client) — A Practical Guide for Experienced Developers

If you’ve spent years using tools like Postman, you already understand the value of structured API testing, collections, environments, and documentation. But as projects mature, you may start wanting something:

• Lightweight
• Version-controlled
• Close to the codebase
• Zero context switching

That’s where the REST Client extension in VS Code with .http files becomes a serious alternative.

For a 4–5 year experienced developer, this isn’t about replacing Postman. It’s about:

• Keeping API examples in Git
• Reducing tool overhead
• Treating API calls as documentation
• Making backend repos self-testable

This guide walks you from installation to advanced environment setup, including two major issues most developers hit:

1. --- vs ### request separation and JSON parsing errors
2. Why rest-client.environment.json sometimes doesn’t work and how .vscode/settings.json solved it

---

1️⃣ Why Use api.http Instead of Postman?

For experienced developers, the real advantages are:

✅ Version Control Friendly

.http files live in your repository. API examples evolve with the backend.

✅ Lightweight

No separate app. No syncing accounts. No collections export.

✅ Documentation + Testing in One

Your api.http becomes living documentation.

✅ CI-Friendly

You can later convert these into automated tests.

---

2️⃣ Installing REST Client in VS Code

1. Open Extensions (Ctrl + Shift + X)
2. Search for:

REST Client

Install:

REST Client by Huachao Mao

Reload VS Code.

---

3️⃣ Creating Your First api.http

Create a file:

api.http

Let’s use a free public API for demo:

We’ll use:

https://jsonplaceholder.typicode.com

---

Example 1 — Simple GET Request

### Get all posts
GET https://jsonplaceholder.typicode.com/posts

Click “Send Request” above it.

You’ll see the response in a new VS Code tab.

That’s it. No GUI required.

---

Example 2 — POST Request

### Create new post
POST https://jsonplaceholder.typicode.com/posts
Content-Type: application/json

{
  "title": "API Testing in VS Code",
  "body": "Using REST Client instead of Postman",
  "userId": 1
}

Clean. Readable. Commit-ready.

---

4️⃣ Separating Multiple Requests (CRITICAL)

When you have multiple requests in one file, you must separate them using:

###

Correct:

### Get posts
GET https://jsonplaceholder.typicode.com/posts

###

### Get single post
GET https://jsonplaceholder.typicode.com/posts/1

---

🚨 BIG ISSUE #1 — --- vs ###

Many developers coming from Markdown or other tools use:

---

This is WRONG for REST Client.

If you write:

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

{
  "name": "Ajit"
}
---

VS Code will send this entire block:

{
  "name": "Ajit"
}
---

And your backend (for example, Django REST Framework) will throw:

JSON parse error - Extra data

Because:

--- is treated as part of the JSON body.

✅ Rule:

Only ### separates requests.

Nothing else works.

---

5️⃣ Using Variables (Cleaner & Reusable)

Instead of hardcoding URLs:

@baseUrl = https://jsonplaceholder.typicode.com

### Get posts
GET {{baseUrl}}/posts

Works immediately.

But this doesn’t solve environment-specific values like tokens.

---

6️⃣ Setting Up Environments (Local & Production)

There are two approaches:

---

❌ Attempt 1 — rest-client.environment.json (Did Not Work Initially)

You create:

rest-client.environment.json

In project root:

{
  "local": {
    "baseUrl": "http://127.0.0.1:8000",
    "authToken": "real-token"
  },
  "prod": {
    "baseUrl": "https://api.example.com",
    "authToken": "prod-token"
  }
}

And use:

GET {{baseUrl}}/api/users
Authorization: Token {{authToken}}

Expected behavior:
Bottom-right environment selector appears.

Problem:
It didn’t appear.

Why?

Because in some workspace setups:

• Multi-root workspace
• Custom VS Code config
• REST Client not auto-detecting root file

The extension didn’t auto-load the file.

---

✅ Final Working Solution — .vscode/settings.json

Inside project root:

.vscode/settings.json

Add:

{
  "rest-client.environmentVariables": {
    "local": {
      "baseUrl": "http://127.0.0.1:8000",
      "authToken": "your-real-token"
    },
    "prod": {
      "baseUrl": "https://api.example.com",
      "authToken": "prod-token"
    }
  }
}

Reload VS Code.

Now:

• Open .http
• Bottom-right shows environment selector
• Choose local or prod

Variables resolve correctly.

Problem solved.

---

⚠️ Important Security Note

.vscode/settings.json now contains tokens.

That means:

You MUST add this to .gitignore:

.vscode/

Otherwise you risk committing:

• API tokens
• Secrets
• Environment configs

Safer production pattern:

.vscode/settings.json          (ignored)
.vscode/settings.example.json  (committed template)

Example template:

{
  "rest-client.environmentVariables": {
    "local": {
      "baseUrl": "http://127.0.0.1:8000",
      "authToken": "paste-token-here"
    }
  }
}

---

7️⃣ Final Clean Project Structure

project/
│
├── api.http
├── .vscode/
│   └── settings.json   (ignored)
├── .gitignore
└── README.md

.gitignore:

.vscode/

---

8️⃣ When Should You Still Use Postman?

Use Postman when:

• You need automated test scripting
• Team collaboration on collections
• Complex OAuth flows
• Mock servers

Use api.http when:

• You want repo-based documentation
• Backend development speed matters
• You want zero tool switching
• You prefer Git-tracked API specs

---

9️⃣ Final Thoughts

For experienced developers, api.http with REST Client feels like:

• curl, but readable
• Postman, but version-controlled
• Documentation, but executable

It removes friction.

And once you fix:

• --- vs ###
• Environment configuration quirks

It becomes a powerful, lightweight part of your backend workflow.