HTTP Client Library

A Go HTTP client library with built-in caching, authentication, and automatic background updates.

🚀 Quick Start (2 minutes)

Basic HTTP Client

// 1. Import the packageimport"github.com/samhoque/httpclient"// 2. Create a clientclient:=httpclient.NewClient(
"https://api.example.com",
httpclient.WithTimeout(10*time.Second),
httpclient.WithAuth(), // Enable cookie handling
)
// 3. Make requests// Basic requestresp, err:=client.Get(context.Background(), "/users")
// Request with custom headersresp, err=client.Get(context.Background(), "/users",
httpclient.WithRequestHeader("X-Request-ID", "123"),
)
// POST with dataresp, err=client.Post(context.Background(), "/users", user)

Authentication Example

// Create client with auth enabledclient:=httpclient.NewClient(
"https://api.example.com",
httpclient.WithAuth(),
)
// Login - cookies will be automatically savedloginData:=struct {
Usernamestring`json:"username"`Passwordstring`json:"password"`
}{
Username: "user@example.com",
Password: "password123",
}
resp, err:=client.Post(ctx, "/login", loginData)
// Subsequent requests will automatically include saved cookiesresp, err=client.Get(ctx, "/protected-endpoint")

Cached HTTP Client

// 1. Create a cached clientclient:=httpclient.NewCachedClient("https://api.example.com")
deferclient.Stop()
// 2. Define your data structurevarusers []struct {
IDint`json:"id"`Namestring`json:"name"`
}
// 3. Setup automatic cache updateserr:=client.SetupCachedEndpoint(
context.Background(),
httpclient.CacheConfig{
Path: "/users",
CronSpec: "*/15 * * * *", // Every 15 minutesExpiration: 20*time.Minute,
},
&users,
)
// 4. Use the cached datadata, err:=client.GetCached("/users")

📦 Installation

go get github.com/samhoque/httpclient

🔥 Common Use Cases

1. API Client with Authentication

client:=httpclient.NewClient(
"https://api.example.com",
httpclient.WithAuth(),
httpclient.WithTimeout(5*time.Second),
)

2. Per-Request Headers

// Add custom headers for specific requestsresp, err:=client.Get(ctx, "/users", httpclient.WithRequestHeader("X-Custom-Header", "value"),
httpclient.WithRequestHeader("X-Request-ID", "123"),
)
// Different headers for another requestresp, err=client.Post(ctx, "/data", data,
httpclient.WithRequestHeader("Authorization", "Bearer token"),
)

3. Cached API Data with Auto-Updates

client:=httpclient.NewCachedClient("https://api.example.com")
deferclient.Stop()
varprices []PriceDataerr:=client.SetupCachedEndpoint(
context.Background(),
httpclient.CacheConfig{
Path: "/prices",
CronSpec: "*/5 * * * *", // Update every 5 minutesExpiration: 10*time.Minute,
},
&prices,
)

⚡️ Features At a Glance

Basic Client

• ✅ Automatic JSON encoding/decoding
• ✅ Custom headers and timeouts
• ✅ Context support
• ✅ Clean, fluent API
• ✅ Per-request headers
• ✅ Cookie-based authentication

Authentication

• ✅ Automatic cookie handling
• ✅ Session persistence
• ✅ Support for cookie-based auth flows
• ✅ Per-request header customization

Cached Client

• ✅ Automatic background updates
• ✅ In-memory caching
• ✅ Configurable update schedules
• ✅ Thread-safe operations

🔧 Configuration Options

Client Options

• WithTimeout(duration) - Set client timeout
• WithHeader(key, value) - Add default headers
• WithAuth() - Enable cookie handling

Request Options

• WithRequestHeader(key, value) - Add headers to specific requests

📝 Common Cron Patterns

CacheConfig{
CronSpec: "*/15 * * * *"// Every 15 minutesCronSpec: "0 * * * *"// Every hourCronSpec: "0 0 * * *"// Every day at midnight
}

🚨 Error Handling

// Basic error handlingresp, err:=client.Get(ctx, "/users")
iferr!=nil {
iferrors.Is(err, context.DeadlineExceeded) {
// Handle timeout
}
returnerr
}
deferresp.Body.Close()
// Cache error handlingdata, err:=client.GetCached("/users")
iferr!=nil {
// If cache expired, fetch fresh datadata, err=client.GetCachedOrFetch(ctx, "/users")
}

🔍 Advanced Usage

Authentication with Custom Headers

client:=httpclient.NewClient(
"https://api.example.com",
httpclient.WithAuth(),
)
// Login with custom headersresp, err:=client.Post(ctx, "/login", loginData,
httpclient.WithRequestHeader("X-Device-ID", "device123"),
)
// Subsequent authenticated requestsresp, err=client.Get(ctx, "/profile",
httpclient.WithRequestHeader("X-Request-ID", "req123"),
)

Custom Configuration

client:=httpclient.NewClient(
"https://api.example.com",
httpclient.WithAuth(),
httpclient.WithTimeout(5*time.Second),
httpclient.WithHeader("X-API-Key", "key"),
)

⚠️ Common Gotchas

1. Always defer client.Stop() for cached clients
2. Always defer resp.Body.Close() for responses
3. Cache expiration is separate from update schedule
4. Cookie handling requires WithAuth() option

🤝 Need Help?

• Report issues: GitHub Issues
• Contribute: GitHub Repository

Full API Reference

For complete API documentation, see our GoDoc.