GoLand's HTTP Client: Turning .http Files into Executable Docs for Go Handlers

You have a Go handler that reads a query parameter, calls a service, and returns JSON. To verify it works, you either paste a curl command into a terminal, click around in Postman, or scaffold a temporary test file. Each option forces a context switch: you leave the editor, lose your place in the handler code, and manually reconstruct the request you just imagined.

GoLand's built-in HTTP client offers a narrower but faster path. By writing .http files beside your handler code, you can send requests, inspect responses, and keep a reusable record of how your API behaves—all without leaving the IDE. Used deliberately, these files become executable API documentation and a lightweight smoke-test layer for local development.

The context-switching tax

When you are deep in a handler, the cost of switching tools is not just the seconds spent typing a URL. It is the loss of context. You are looking at a struct definition in one window and a terminal in another. If the response is wrong, you have to mentally map the error back to the line of code that produced it.

An .http file keeps the request next to the source. Because the HTTP client is a cross-product JetBrains feature, GoLand users get the same request/response workflow available in other JetBrains IDEs, plus Go-specific navigation: in many setups, you can jump from a request URL to the handler registration or definition. That small integration shortens the loop between "I changed the handler" and "I see the new response."

A worked example: health-check handler

Suppose you have a simple handler in handlers/health.go:

package handlers

import (
    "encoding/json"
    "net/http"
)

func Health(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}

Create a file named scratch.http in the same directory. GoLand applies HTTP syntax highlighting and code completion to .http files automatically. Add a request:

### Health check
GET http://localhost:8080/health
Accept: application/json

The ### line separates requests and gives each one a name. A gutter icon appears next to the request; clicking it sends the request. The response—status code, headers, and body—appears in the HTTP Client tool window. You do not need to copy the URL into a browser or construct a curl flag string.

To make this work, start your Go server from a Run configuration in GoLand. The HTTP client does not launch the binary for you; it sends the request to whatever address you specify. If the server is not running, the request fails with a connection error, which is the expected check that your local process is alive.

Parameterization without hardcoded values

Repeating http://localhost:8080 in every request gets old. GoLand's HTTP client supports environment variables through a file named http-client.env.json. Place it in your project root and define named environments:

{
  "dev": {
    "baseUrl": "http://localhost:8080",
    "userId": "42"
  }
}

Now your request can reference those values:

### Get user
GET {{baseUrl}}users/{{userId}}
Accept: application/json

Select the dev environment in the HTTP Client UI, and GoLand substitutes the variables before sending. This keeps the .http file shareable: teammates can run the same requests against their own local ports by editing their own environment file.

Security caution: never commit real credentials, API keys, or tokens inside .http files or http-client.env.json. If your team shares the file in version control, use placeholder values and inject secrets through IDE-scoped private files or environment variables that are excluded from Git. Add http-client.env.json to .gitignore if it contains anything sensitive.

Where the HTTP client stops

This tool is for manual exploration and smoke testing—a quick check that the happy path returns 200 and the expected shape. It is not a replacement for Go's testing package or CI pipelines. Complex table-driven tests, database rollback, and concurrent scenarios belong in go test.

Response handler scripts let you write basic assertions against the response body or status code, but they are intentionally limited. Complex validation logic quickly becomes unreadable inside an IDE script. If you find yourself writing multi-step conditional checks, move that logic into a Go test.

Authentication is another boundary. Simple bearer tokens or basic auth work fine as headers. Full OAuth redirects, cookie jar management, and multi-step login flows usually require an external harness or a dedicated integration test.

Finally, version drift matters. The exact directive names, pre-request script variables, and response handler syntax have changed across GoLand releases. Do not assume a script you read in a blog post works identically in your installed build. Open the built-in HTTP client reference in your IDE to confirm which variables and directives are available.

An actionable next step

Pick one handler you are actively debugging. Create a .http file beside it. Add a single GET request for the success case, start your server from a Run configuration, and send the request. Then define one environment variable in http-client.env.json to remove a hardcoded value. Keep the file in version control as living documentation for the next developer—or the next you—but keep the secrets out. The result is a faster feedback loop and a clearer record of how your Go API is supposed to behave.