IntelliJ HTTP Client Guide

The Milesoft Platform leverages IntelliJ IDEA's native HTTP Client as the primary mechanism for executing local integration tests, exploring APIs, and managing secure environments.

This approach provides a declarative, text-based environment for HTTP requests, completely integrated into your IDE workflow and safely decoupled from UI-based clients.

1. Why the IntelliJ HTTP Client?

Traditional API testing tools (like Postman or Insomnia) store requests in proprietary databases, which makes them difficult to version control, review, or share across team members.

By contrast, the IntelliJ HTTP Client uses plain-text .http files. These files:

  • Can be committed directly to Git: Track API request histories, headers, and payloads alongside your code changes.
  • Support environment variables: Securely swap configurations between development, sandbox, and production environments via http-client.env.json and http-client.private.env.json files.
  • Are lightweight and fast: Execute directly within your IDE without spawning heavy external applications.

2. Core Components & Structure

Every bootstrapped Milesoft project includes pre-configured .http and .env.json files under src/test/http/. Let's explore how they work.

2.1 The Request File (src/test/http/requests.http)

An .http file defines one or more HTTP requests using standard plain-text syntax.

### Get Application Health Actuator
GET http://localhost:8080/actuator/health
Accept: application/json

### Register a User (Protected Endpoint)
POST {{baseUrl}}/api/v2/users
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "email": "developer@acme.com",
  "roles": "ROLE_DEVELOPER"
}
  • Separators (###): Divide individual request definitions. In IntelliJ, a small green Play/Arrow button appears in the gutter next to each request. Click it to run that specific request.
  • Placeholders ({{baseUrl}}, {{token}}): Dynamically reference variables defined in your environment files.

2.2 Public Environments (src/test/http/http-client.env.json)

This file defines non-sensitive environmental variables (like URLs) for different profiles.

{
  "sand": {
    "baseUrl": "https://company-app-sand-abc123-uw.a.run.app"
  },
  "prod": {
    "baseUrl": "https://company-app-prod-abc123-uw.a.run.app"
  }
}

2.3 Private Secrets (src/test/http/http-client.private.env.json)

Sensitive keys, credentials, and access tokens belong in your private environment file.

  • Crucial: This file is automatically gitconfigured inside your .gitignore and must never be committed to your repository.
{
  "sand": {
    "token": "milesoft_token_sandbox_decrypted_value_here"
  },
  "prod": {
    "token": "milesoft_token_production_decrypted_value_here"
  }
}

3. Alternative: Standard Command Line (curl)

While the IntelliJ HTTP Client is our recommended tool due to its deep integration and version control capabilities, you are absolutely free to use standard curl or any other HTTP utility of your choice.

Here is how the above protected POST request translates directly to a standard curl command:

curl -X POST https://company-app-sand-abc123-uw.a.run.app/api/v2/users \
  -H "Authorization: Bearer milesoft_token_sandbox_decrypted_value_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@acme.com",
    "roles": "ROLE_DEVELOPER"
  }'

4. Learn More

For an in-depth reference on request syntax, script-based testing, response handling, and advanced features, refer to the official JetBrains documentation: