DEV Community

Cover image for Stop Clicking Around: API Testing with `.http` Files (From Beginner to Pro)
Ajit Kumar
Ajit Kumar

Posted on

Stop Clicking Around: API Testing with `.http` Files (From Beginner to Pro)

#http #rest #api #testing

Modern API development does not require heavyweight GUI tools. If you are building APIs with Django REST Framework or any backend stack, you can test, document, and version your APIs using simple .http files — directly inside Visual Studio Code.

This tutorial walks from beginner to advanced usage of the .http approach, compares it with tools like Postman, HTTPie, and Swagger, and shows how to build a clean, executable API workflow.

Why .http Files?

A .http file is a plain text file containing HTTP requests.

Example:

GET http://127.0.0.1:8000/api/blogs/
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

With the REST Client extension in VS Code, you can:

  • Click “Send Request”
  • See status code
  • View headers
  • Inspect JSON response
  • Measure response time

All without leaving your editor.

This gives you:

  • Executable documentation
  • Version-controlled API tests
  • Zero external dependency
  • Simple text-based workflow

Part 1 — Beginner Level

Step 1: Install REST Client

Open VS Code → Extensions → Install:

REST Client (by Huachao Mao)

Step 2: Create api.http

Create a file:

api.http
Enter fullscreen mode Exit fullscreen mode

Add:

@baseUrl = http://127.0.0.1:8000

### List Blogs
GET {{baseUrl}}/api/blogs/
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Start your server:

python manage.py runserver
Enter fullscreen mode Exit fullscreen mode

Click Send Request.

You’ll see:

  • 200 OK
  • Response body
  • Headers
  • Timing

That’s it.

You just tested your API with a text file.

Part 2 — Intermediate Usage

Now let’s add CRUD operations.

### Create Blog
POST {{baseUrl}}/api/blogs/
Content-Type: application/json

{
  "title": "API Testing Simplified",
  "content": "Using .http files improves workflow."
}

### Get Blog by ID
GET {{baseUrl}}/api/blogs/1/

### Update Blog
PUT {{baseUrl}}/api/blogs/1/
Content-Type: application/json

{
  "title": "Updated Title",
  "content": "Updated content."
}

### Delete Blog
DELETE {{baseUrl}}/api/blogs/1/
Enter fullscreen mode Exit fullscreen mode

Now your file:

  • Documents endpoints
  • Stores example payloads
  • Acts as test suite
  • Becomes team reference

Part 3 — Advanced Techniques

1️⃣ Environment Switching

At the top:

@baseUrl = http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode

Change to:

@baseUrl = https://staging.myapp.com
Enter fullscreen mode Exit fullscreen mode

All requests update automatically.

2️⃣ Variables from Response

You can extract response data:

### Create Blog
POST {{baseUrl}}/api/blogs/
Content-Type: application/json

{
  "title": "Dynamic Test",
  "content": "Testing extraction"
}
Enter fullscreen mode Exit fullscreen mode

Then reference:

GET {{baseUrl}}/api/blogs/{{createBlog.response.body.id}}/
Enter fullscreen mode Exit fullscreen mode

Now requests become chained.

3️⃣ Authentication Headers 

@token = your_jwt_token_here

GET {{baseUrl}}/api/secure-endpoint/
Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

4️⃣ Expected Response Documentation

You can document expected behavior:

# Expected 201 Created
# Metadata should auto-generate

POST {{baseUrl}}/api/blogs/
Content-Type: application/json

{
  "title": "AI",
  "content": "AI is powerful."
}
Enter fullscreen mode Exit fullscreen mode

This becomes living API documentation.

How It Compares to Other Tools

1️⃣ Postman

Postman is powerful:

Pros:

  • GUI
  • Team collaboration
  • Automated test scripts
  • Cloud sync

Cons:

  • Requires account
  • Harder to version-control cleanly
  • Collections stored outside codebase
  • Heavy UI

.http advantage:

  • Lives in repo
  • Lightweight
  • No login
  • Git diff-friendly

2️⃣ HTTPie

HTTPie is CLI-based.

Example:

http GET http://127.0.0.1:8000/api/blogs/
Enter fullscreen mode Exit fullscreen mode

Pros:

  • Beautiful CLI output
  • Fast
  • Scriptable

Cons:

  • Not self-documenting
  • Not clickable
  • Harder for beginners

.http sits between curl and Postman — readable and interactive.

3️⃣ Swagger / OpenAPI

Swagger auto-generates API documentation.

Pros:

  • Interactive UI
  • Schema validation
  • Industry standard

Cons:

  • Generated, not curated
  • Harder to add narrative examples
  • Not ideal for manual test workflows

Best practice:

Use Swagger for:

  • Public documentation
  • API contracts

Use .http for:

  • Development testing
  • Internal API examples
  • Regression testing

Why .http is Excellent for Teams

  1. Stored in Git
  2. Reviewable via pull request
  3. Encourages documented APIs
  4. Works offline
  5. Zero SaaS dependency
  6. Reproducible environments

Your repository now contains:

api.http
Enter fullscreen mode Exit fullscreen mode

Which acts as:

  • API spec
  • Test runner
  • Example library
  • Debug tool

Scaling the Pattern

For large systems:

/api-tests/
    blog.http
    auth.http
    analytics.http
Enter fullscreen mode Exit fullscreen mode

Organize per domain.

For multi-version APIs:

/api-tests/v1/
Enter fullscreen mode Exit fullscreen mode

When Not to Use .http

  • Load testing (use k6 or Locust)
  • Automated CI assertions (use pytest + requests)
  • Public API documentation portal (use OpenAPI)

It is a developer-first tool, not an enterprise API gateway.

Final Recommendation

For solo developers, small teams, backend-focused engineers:

.http + VS Code is the fastest, cleanest API testing workflow available.

It removes friction.
It keeps documentation close to code.
It scales from beginner to advanced usage.

And it avoids unnecessary tooling overhead.

Top comments (0)