Using IntelliJ IDEA’s Built‑in HTTP Client for API Development

Problem: Keeping API requests close to the code

When you work on a backend service, you often need to test endpoints repeatedly. Switching to a separate GUI tool like Postman means your requests live outside the project, making it harder to see which request exercises which endpoint and to share them in pull requests.

Thesis: IntelliJ IDEA’s HTTP Client lets you write, run, and version‑control requests directly in the IDE

The client treats request files as plain text (.http or .rest) that sit alongside your source code. You can define environments, chain requests with JavaScript response handlers, and diff changes in Git just like any other file.

1. Creating a request file

In any JetBrains IDE that includes the HTTP Client (IntelliJ IDEA Ultimate, PyCharm Professional, etc.), create a file named api.http in your project root. The gutter to the left of each request shows a run icon.

### Get a public resource
GET https://api.example.com/ping
Accept: application/json

Click the run icon; the Response tab appears at the bottom, showing status, headers, and body. No external tool is required.

2. Switching environments with variable files

Define shared variables in http-client.env.json (checked into Git) and secrets in http-client.private.env.json (added to .gitignore). Each file contains a JSON object where keys are environment names.

// http-client.env.json
{
  "dev": {
    "host": "https://dev.api.example.com",
    "username": "dev_user"
  },
  "staging": {
    "host": "https://staging.api.example.com",
    "username": "stage_user"
  }
}

In your request, reference variables with double curly braces:

### Login
POST {{host}}/auth/login
Content-Type: application/json

{
  "username": "{{username}}",
  "password": "{{password}}"
}

Use the environment selector in the top‑right of the editor to switch between dev, staging, etc. The selector changes which values are substituted at runtime.

3. Chaining requests with response handlers

After a successful login you often need to reuse an auth token in subsequent calls. Add a JavaScript handler after the request:

### Login
POST {{host}}/auth/login
Content-Type: application/json

{
  "username": "{{username}}",
  "password": "{{password}}"
}

> {%
  // If the login succeeds, store the token for later requests
  if (response.status === 200) {
    client.global.set("authToken", response.json.body.token);
  }
%}

Now a following request can insert the token:

### Get user profile
GET {{host}}/users/me
Authorization: Bearer {{authToken}}
Accept: application/json

Run the login request first; the handler stores authToken globally. Running the profile request then sends the token automatically.

Trade‑offs and limitations

• Edition requirement: The full HTTP Client is available only in paid JetBrains IDEs (e.g., IntelliJ IDEA Ultimate). The Community edition lacks the run gutter and response viewer.
• Scripting API changes: The response‑handler syntax shown above works in recent releases (2023.2+). Older examples using response.content or client.put may fail; consult the IDE’s help (Help → HTTP Client) for the current API.
• Secret handling: http-client.private.env.json is ignored by Git, but values are stored in plain text. For production‑grade secrets you still need a vault or similar solution.

Actionable closing

To verify that the client works for you:

1. Create a scratch test.http file with a simple GET to a public endpoint (e.g., https://httpbin.org/get).
2. Confirm the run icon appears and click it; inspect the Response tab for a 200 status and JSON body.
3. Add an environment block to http-client.env.json with a variable baseUrl and rewrite the request to use {{baseUrl}}/get. Switch environments and observe the URL change in the request preview.
4. Add a response handler that captures a field from the JSON (e.g., client.global.set("origin", response.json.body.origin);) and a second request that references {{origin}}. Run the first, then the second, and verify the second request shows the captured value.

If each step behaves as described, you have a working, version‑control‑friendly API testing workflow inside your IDE. For teams using the Community edition, consider sharing the .http files via a repository and using a lightweight external runner (e.g., curl) for execution, but note that you lose the inline response viewer and handler scripting.