Stop Exporting Postman Collections: Using WebStorm's Built-in HTTP Client

The API Testing Drift Problem

Most developers rely on external GUI tools like Postman or Insomnia to test REST endpoints. While powerful, these tools create a synchronization gap: the API code lives in Git, but the tests live in a proprietary cloud account or a JSON export file that is rarely updated. When a teammate changes a route or a required header, the shared collection breaks, and the fix involves a manual cycle of updating the tool and re-exporting the collection.

The solution is to treat your API requests as code. By using WebStorm's built-in HTTP Client, you move your request definitions into .http files that live directly in your project repository. This ensures that every pull request updating an endpoint also updates the test that verifies it.

Version-Controlled Requests

WebStorm allows you to create files with the .http or .rest extension. These are plain-text files that follow a standard HTTP request format. Because they are text, they are subject to the same code review process as your TypeScript or JavaScript logic.

You can separate multiple requests within a single file using ###. This allows you to group related endpoints—such as all /users routes—into one file without needing a complex folder hierarchy in an external app.

Managing Environments and Secrets

Hardcoding URLs like localhost:3000 is impractical when you need to test against staging or production. WebStorm handles this via environment files (http-client.env.json).

You can define a public environment file for shared configurations and a private one (http-client.private.env.json) for sensitive tokens. The private file should be added to your .gitignore to prevent secrets from leaking into your repository.

Example Configuration

Create a file named http-client.env.json in your project root:

{
  "dev": {
    "host": "http://localhost:3000",
    "api_key": "dev-key-123"
  },
  "staging": {
    "host": "https://staging.api.example.com",
    "api_key": "staging-key-456"
  }
}

Then, reference these variables in your test-api.http file. Switching between dev and staging is a dropdown selection in the editor toolbar:

GET {{host}}/api/v1/status
Authorization: Bearer {{api_key}}

###

POST {{host}}/api/v1/users
Content-Type: application/json

{
  "name": "Technical Editor",
  "email": "[contact removed]"
}

Automating Workflows with Response Handlers

One of the biggest hurdles in moving away from GUI tools is the loss of "chaining" (e.g., using a token from a login response in a subsequent request). WebStorm solves this with JavaScript-based response handlers. By adding a script block starting with > {%, you can programmatically capture data from the response body and assert on the result.

Example: Chaining an Auth Token

POST {{host}}/api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "password123"
}

> {%
  client.assert(response.status === 200, "Login failed");
  client.global.set("auth_token", response.body.token);
%}

###

GET {{host}}/api/protected-route
Authorization: Bearer {{auth_token}}

When you run the login request, the handler extracts the token and saves it to a global variable, which the second request immediately consumes. Because the requests run inside the IDE, a failing call is one click away from the route handler or controller code that serves it—no copy-pasting between tools.

Trade-offs and Limitations

The built-in client is designed for the developer's inner loop, not for full-scale API lifecycle management. It lacks the mock servers, automated monitors, and polished public documentation portals found in dedicated platforms. If your primary goal is to provide a public-facing API catalog for external partners, a dedicated tool is still necessary.

Additionally, the response handler scripts use a JetBrains-specific JavaScript API, meaning these scripts cannot be ported to other tools or run in a standard Node.js environment. Feature availability also varies by WebStorm version and license tier, so confirm the HTTP Client is bundled in your release before standardizing on it.

Verifying Your Setup

To confirm the client is working in your version of WebStorm:

1. Create a new file named test.http in any project.
2. Enter GET https://httpbin.org/get.
3. Click the green Run icon in the gutter (the left margin). No special permissions are required; the request runs as your local user.
4. Verify that the response pane opens and displays the JSON response from httpbin.

If the run icon does not appear, check that the HTTP Client plugin is enabled under Settings > Plugins. Once verified, commit your first .http file alongside the endpoint it tests—and let the next API change update both in the same commit.