# How to Use HTTP Client Helpers in httpx for GET and POST Requests

> Streamline your Go apps with httpx client helpers for GET POST JSON POST form and XML requests In gorig by jom-io enjoy built-in timeouts and error handling

- Repository: [Jom/gorig](https://github.com/jom-io/gorig)
- Tags: how-to-guide
- Published: 2026-03-04

---

**The `httpx` package in `jom-io/gorig` provides centralized HTTP client helpers with built-in timeout handling, consistent error wrapping, and convenient methods for GET, POST JSON, POST form, and XML requests, including Gin context integration for automatic header forwarding.**

The `httpx` package in the `jom-io/gorig` repository simplifies HTTP communication in Go applications by wrapping the standard `net/http` client with utilities for timeout management, error handling, and common request patterns. Whether you need to fetch JSON data from an external API or POST form data to a legacy endpoint, these HTTP client helpers in httpx reduce boilerplate while ensuring consistent error reporting through the repository's custom error types.

## Core Features of the httpx Package

The `httpx` implementation in [`httpx/http.go`](https://github.com/jom-io/gorig/blob/main/httpx/http.go) centers on a shared `*http.Client` configured with a **default timeout of 120 seconds**. This client is accessed via `getClient()` and can be temporarily overridden using `SetTimeOutTmp` for specific requests requiring different timeout behavior.

All network errors are wrapped using the repository's `*utils/errors.Error` type (defined in [`utils/errors/err.go`](https://github.com/jom-io/gorig/blob/main/utils/errors/err.go)), providing stack traces and uniform error inspection across the codebase. For debugging, `PostJSONResp` utilizes the `utils/logger` package to emit outbound JSON payloads.

## Making GET Requests with httpx Helpers

### Simple GET with Query Parameters

The `Get` function constructs a URL with encoded query parameters and returns the response body as a string. This is the most basic HTTP client helper in httpx for retrieval operations.

```go
package main

import (
	"fmt"

	"github.com/jom-io/gorig/httpx"
)

func main() {
	params := map[string]string{
		"q":    "golang",
		"page": "1",
	}
	body, err := httpx.Get("https://api.example.com/search", params)
	if err != nil {
		fmt.Println("request failed:", err)
		return
	}
	fmt.Println("response body:", body)
}

```

*Implementation reference:* `Get` builds the URL and uses `http.Get` – see lines 38‑60 in [[`httpx/http.go`](https://github.com/jom-io/gorig/blob/main/httpx/http.go)](https://github.com/jom-io/gorig/blob/master/httpx/http.go#L38-L60).

### GET with Custom Headers

When you need to attach authentication tokens or content-type specifications, use `GetHeader`. This helper creates an `http.NewRequest`, attaches the provided header map, and executes the request with the shared client.

```go
package main

import (
	"fmt"

	"github.com/jom-io/gorig/httpx"
)

func main() {
	headers := map[string]string{
		"Authorization": "Bearer abc123",
		"Accept":        "application/json",
	}
	body, err := httpx.GetHeader("https://api.example.com/profile", nil, headers)
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println(body)
}

```

*Implementation reference:* `GetHeader` creates a request, sets each header, and executes it – see lines 72‑90 in the same file.

### GET and Parse JSON Response

For APIs returning JSON, `GetMap` and `GetMapHeader` combine the retrieval logic with automatic unmarshaling into `map[string]interface{}`. These helpers eliminate manual JSON parsing boilerplate.

```go
package main

import (
	"fmt"

	"github.com/jom-io/gorig/httpx"
)

func main() {
	data, err := httpx.GetMap("https://api.example.com/config", nil)
	if err != nil {
		fmt.Println("failed:", err)
		return
	}
	// data is a map[string]interface{}
	fmt.Printf("config version: %v\n", data["version"])
}

```

*Implementation reference:* `GetMap` calls `Get` then `ParseJSON` – see lines 93‑99.

## Making POST Requests with httpx Helpers

### POST Form Data

The `PostForm` helper handles `application/x-www-form-urlencoded` submissions, automatically encoding the parameter map into `url.Values` and using `http.PostForm`.

```go
package main

import (
	"fmt"

	"github.com/jom-io/gorig/httpx"
)

func main() {
	form := map[string]string{
		"username": "alice",
		"password": "secret",
	}
	resp, err := httpx.PostForm("https://api.example.com/login", form)
	if err != nil {
		fmt.Println("login error:", err)
		return
	}
	fmt.Println("login response:", resp)
}

```

*Implementation reference:* `PostForm` builds `url.Values` and uses `http.PostForm` – lines 109‑127.

### POST JSON Payloads

For REST APIs expecting JSON, `PostJSON` marshals your struct or map, sets the `Content-Type: application/json` header, and returns the parsed response as a map. The underlying `PostJSONResp` performs the actual request and logs the outbound payload for debugging.

```go
package main

import (
	"fmt"

	"github.com/jom-io/gorig/httpx"
)

type Order struct {
	ItemID   string `json:"item_id"`
	Quantity int    `json:"quantity"`
}

func main() {
	order := Order{ItemID: "XYZ", Quantity: 3}
	result, err := httpx.PostJSON("https://api.example.com/orders", order)
	if err != nil {
		fmt.Println("order failed:", err)
		return
	}
	fmt.Printf("order ID: %v, status: %v\n", result["id"], result["status"])
}

```

*Implementation reference:* `PostJSON` → `PostJSONResp` (JSON marshal, POST, read body) → `ParseJSON` – see lines 129‑193.

### POST with Custom Headers

When you need to attach authentication or request IDs to JSON POSTs, use `PostJSONHeader`. This variant accepts a header map and forwards it to the underlying request builder.

```go
package main

import (
	"fmt"

	"github.com/jom-io/gorig/httpx"
)

func main() {
	payload := map[string]string{"msg": "hello"}
	headers := map[string]string{
		"Authorization": "Bearer xyz987",
	}
	resp, err := httpx.PostJSONHeader("https://api.example.com/echo", payload, headers)
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println("server echoed:", resp)
}

```

*Implementation reference:* `PostJSONHeader` builds a request, injects the header map, and reuses `PostJSONRespHeader` – see lines 95‑104 and 153‑173.

### POST XML Data

For legacy SOAP or XML-based services, `PostXML` manually constructs an XML document from a map and posts it with `Content-Type: application/xml`.

*Implementation reference:* `PostXML` is implemented in the same file alongside `ParseXML` for response handling.

## Gin Integration and Request Context

### Forwarding Authorization Headers

The `httpx` package provides Gin-aware helpers that simplify token propagation in microservice architectures. `PostJSONByCtx` extracts the `Authorization` header from the incoming Gin context and forwards it to the downstream service automatically.

```go
func handler(c *gin.Context) {
	// Assume downstream expects the same Authorization token
	body, err := httpx.PostJSONByCtx(c, "https://api.example.com/forward", map[string]string{"data": "value"})
	if err != nil {
		c.JSON(500, gin.H{"error": err.Error()})
		return
	}
	c.JSON(200, body)
}

```

*Implementation reference:* `PostJSONByCtx` extracts `Authorization` from the Gin context and calls `PostJSONHeader` – see lines 206‑214 in [`httpx/http.go`](https://github.com/jom-io/gorig/blob/main/httpx/http.go).

Similarly, `GetByCtx` performs the same header extraction for GET requests, ensuring consistent authentication propagation across service boundaries.

## Timeout and Error Handling

### Configuring Request Timeouts

All helpers rely on a shared `*http.Client` initialized with a **default timeout of 120 seconds**. You can temporarily override this duration for specific requests using `SetTimeOutTmp`, which modifies the client timeout for the next request only.

```go
// Temporarily set a 30-second timeout for this request only
httpx.SetTimeOutTmp(30 * time.Second)
body, err := httpx.Get("https://slow-api.example.com/data", nil)

```

### Understanding Error Wrapping

Every network or parsing error is wrapped using the repository's custom `*utils/errors.Error` type (defined in [`utils/errors/err.go`](https://github.com/jom-io/gorig/blob/main/utils/errors/err.go)). This provides stack traces and uniform error inspection across the codebase, allowing you to handle HTTP failures consistently whether they originate from connection timeouts, status code errors, or JSON parsing failures.

## Summary

- The `httpx` package in `jom-io/gorig` wraps Go's standard `net/http` with a shared client featuring a 120-second default timeout and centralized error handling via `utils/errors`.
- **GET requests** are handled by `Get` (simple string response), `GetHeader` (custom headers), and `GetMap`/`GetMapHeader` (automatic JSON parsing into maps).
- **POST requests** support form encoding (`PostForm`), JSON payloads (`PostJSON`, `PostJSONHeader`), and XML (`PostXML`), with `PostJSONResp` providing raw response access for debugging.
- **Gin integration** via `PostJSONByCtx` and `GetByCtx` automatically propagates `Authorization` headers from incoming requests to downstream services.
- All errors are wrapped in the repository's custom error type, and timeouts can be temporarily adjusted using `SetTimeOutTmp`.

## Frequently Asked Questions

### How do I add custom headers to a GET request using httpx?

Use the `GetHeader` function defined in [`httpx/http.go`](https://github.com/jom-io/gorig/blob/main/httpx/http.go). Pass your headers as a `map[string]string` as the third argument. This helper creates an `http.NewRequest`, attaches your headers, and executes the request with the shared client.

### What is the default timeout for HTTP requests in httpx?

The default timeout is **120 seconds**. This is configured on the shared `*http.Client` returned by `getClient()`. You can temporarily override this for individual requests using `SetTimeOutTmp(duration)` before making the call.

### How does httpx handle errors from HTTP requests?

All errors are wrapped using the repository's custom `*utils/errors.Error` type (from [`utils/errors/err.go`](https://github.com/jom-io/gorig/blob/main/utils/errors/err.go)). This includes connection failures, timeout errors, non-2xx status codes, and JSON/XML parsing errors. The wrapping preserves stack traces and provides a consistent interface for error inspection across the codebase.

### Can I automatically forward authentication headers when using httpx in a Gin application?

Yes. Use `PostJSONByCtx` or `GetByCtx` (lines 206‑214 in [`httpx/http.go`](https://github.com/jom-io/gorig/blob/main/httpx/http.go)). These helpers extract the `Authorization` header from the incoming Gin context and automatically forward it to the downstream service, simplifying token propagation in microservice architectures.