📚 axios4go - Awesome Go Library for Networking

Go Gopher mascot for axios4go

A Go HTTP client library inspired by Axios, providing a simple and intuitive API for making HTTP requests

🏷️ Networking
📂 HTTP Clients
⭐ 0 stars
View on GitHub 🔗

Detailed Description of axios4go

axios4go

Go Reference Go Report Card Release OpenSSF Best Practices License

axios4go is a Go HTTP client library inspired by Axios (a promise based HTTP client for node.js), providing a simple and intuitive API for making HTTP requests. It offers features like JSON handling, configurable instances, and support for various HTTP methods.

Table of Contents

Features

  • Simple and intuitive API
  • Support for GET, POST, PUT, DELETE, HEAD, OPTIONS, and PATCH methods
  • JSON request and response handling
  • Configurable client instances
  • Global and per-request timeout management
  • Redirect management
  • Basic authentication support
  • Customizable request options
  • Promise-like asynchronous requests
  • Request and response interceptors
  • Upload and download progress tracking
  • Proxy support
  • Configurable max content length and body length
  • Response caching with pluggable storage backends

Installation

To install axios4go, use go get:

go get -u github.com/rezmoss/axios4go

Note: Requires Go 1.13 or later.

Usage

Making a Simple Request

package main

import (
    "fmt"

    "github.com/rezmoss/axios4go"
)

func main() {
    resp, err := axios4go.Get("https://api.example.com/data")
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    fmt.Printf("Status Code: %d\n", resp.StatusCode)
    fmt.Printf("Body: %s\n", string(resp.Body))
}

Using Request Options

resp, err := axios4go.Get("https://api.example.com/data", &axios4go.RequestOptions{
    Headers: map[string]string{
        "Authorization": "Bearer token",
    },
    Params: map[string]string{
        "query": "golang",
    },
})

Making POST Requests

body := map[string]interface{}{
    "name": "John Doe",
    "age":  30,
}
resp, err := axios4go.Post("https://api.example.com/users", body)
if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
}
fmt.Printf("Status Code: %d\n", resp.StatusCode)
fmt.Printf("Body: %s\n", string(resp.Body))

Using Async Requests

axios4go.GetAsync("https://api.example.com/data").
    Then(func(response *axios4go.Response) {
        fmt.Printf("Status Code: %d\n", response.StatusCode)
        fmt.Printf("Body: %s\n", string(response.Body))
    }).
    Catch(func(err error) {
        fmt.Printf("Error: %v\n", err)
    }).
    Finally(func() {
        fmt.Println("Request completed")
    })

Creating a Custom Client

client := axios4go.NewClient("https://api.example.com")

resp, err := client.Request(&axios4go.RequestOptions{
    Method: "GET",
    URL:    "/users",
    Headers: map[string]string{
        "Authorization": "Bearer token",
    },
})
if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
}
fmt.Printf("Status Code: %d\n", resp.StatusCode)
fmt.Printf("Body: %s\n", string(resp.Body))

Using Interceptors

options := &axios4go.RequestOptions{
    InterceptorOptions: axios4go.InterceptorOptions{
        RequestInterceptors: []func(*http.Request) error{
            func(req *http.Request) error {
                req.Header.Set("X-Custom-Header", "value")
                return nil
            },
        },
        ResponseInterceptors: []func(*http.Response) error{
            func(resp *http.Response) error {
                fmt.Printf("Response received with status: %d\n", resp.StatusCode)
                return nil
            },
        },
    },
}

resp, err := axios4go.Get("https://api.example.com/data", options)

Handling Progress

options := &axios4go.RequestOptions{
    OnUploadProgress: func(bytesRead, totalBytes int64) {
        fmt.Printf("Upload progress: %d/%d bytes\n", bytesRead, totalBytes)
    },
    OnDownloadProgress: func(bytesRead, totalBytes int64) {
        fmt.Printf("Download progress: %d/%d bytes\n", bytesRead, totalBytes)
    },
}

resp, err := axios4go.Post("https://api.example.com/upload", largeData, options)

Using Proxy

options := &axios4go.RequestOptions{
    Proxy: &axios4go.Proxy{
        Protocol: "http",
        Host:     "proxy.example.com",
        Port:     8080,
        Auth: &axios4go.Auth{
            Username: "proxyuser",
            Password: "proxypass",
        },
    },
}

resp, err := axios4go.Get("https://api.example.com/data", options)

Response Caching

axios4go supports response caching to reduce network calls. Caching is opt-in and disabled by default.

Basic Usage

import (
    "time"
    "github.com/rezmoss/axios4go"
)

// Create a memory cache
cache := axios4go.NewMemoryCache(&axios4go.MemoryCacheOptions{
    MaxSize:         1000,              // Max entries (0 = unlimited)
    CleanupInterval: 5 * time.Minute,   // Cleanup expired entries
})
defer cache.Close()

// Create client with cache
client := axios4go.NewClientWithCache("https://api.example.com", &axios4go.CacheConfig{
    Cache:      cache,
    DefaultTTL: 5 * time.Minute,
})

// Enable caching for a request
resp, err := client.Request(&axios4go.RequestOptions{
    Method: "GET",
    URL:    "/users",
    Cache:  axios4go.CacheEnabled(10 * time.Minute),
})

Force Refresh

// Bypass cache and fetch fresh data
resp, err := client.Request(&axios4go.RequestOptions{
    Method: "GET",
    URL:    "/users",
    Cache: &axios4go.RequestCacheOptions{
        Enabled:      axios4go.Bool(true),
        TTL:          5 * time.Minute,
        ForceRefresh: true,
    },
})

Custom Cache Key

// Use custom key function to include headers in cache key
client := axios4go.NewClientWithCache("https://api.example.com", &axios4go.CacheConfig{
    Cache:      cache,
    DefaultTTL: 5 * time.Minute,
    KeyFunc: func(method, fullURL string, headers map[string]string) string {
        return method + ":" + fullURL + ":" + headers["Authorization"]
    },
})

Cache Statistics

stats := client.CacheStats()
fmt.Printf("Hits: %d, Misses: %d, Size: %d\n", stats.Hits, stats.Misses, stats.Size)

// Clear cache
client.ClearCache()

Custom Cache Implementation

Implement the Cache interface for custom storage (Redis, file, etc.):

type Cache interface {
    Get(key string) *CacheEntry
    Set(key string, entry *CacheEntry, ttl time.Duration)
    Delete(key string)
    Clear()
    Stats() CacheStats
}

Configuration Options

axios4go supports various configuration options through the RequestOptions struct:

  • Method: HTTP method (GET, POST, etc.)
  • URL: Request URL (relative to BaseURL if provided)
  • BaseURL: Base URL for the request (overrides client's BaseURL if set)
  • Params: URL query parameters (map[string]string)
  • Body: Request body (can be string, []byte, or any JSON serializable object)
  • Headers: Custom headers (map[string]string)
  • Timeout: Request timeout in milliseconds
  • Auth: Basic authentication credentials (&Auth{Username: "user", Password: "pass"})
  • ResponseType: Expected response type (default is "json")
  • ResponseEncoding: Expected response encoding (default is "utf8")
  • MaxRedirects: Maximum number of redirects to follow
  • MaxContentLength: Maximum allowed response content length
  • MaxBodyLength: Maximum allowed request body length
  • Decompress: Whether to decompress the response body (default is true)
  • ValidateStatus: Function to validate HTTP response status codes
  • InterceptorOptions: Request and response interceptors
  • Proxy: Proxy configuration
  • OnUploadProgress: Function to track upload progress
  • OnDownloadProgress: Function to track download progress
  • Cache: Per-request cache configuration (CacheEnabled(ttl) or &RequestCacheOptions{...})

Example:

options := &axios4go.RequestOptions{
    Method: "POST",
    URL:    "/submit",
    Headers: map[string]string{
        "Content-Type": "application/json",
    },
    Body: map[string]interface{}{
        "title":   "Sample",
        "content": "This is a sample post.",
    },
    Auth: &axios4go.Auth{
        Username: "user",
        Password: "pass",
    },
    Params: map[string]string{
        "verbose": "true",
    },
    Timeout:          5000, // 5 seconds
    MaxRedirects:     5,
    MaxContentLength: 1024 * 1024, // 1MB
    ValidateStatus: func(statusCode int) bool {
        return statusCode >= 200 && statusCode < 300
    },
}

resp, err := client.Request(options)

Contributing

Contributions to axios4go are welcome! Please follow these guidelines:

  • Fork the repository and create a new branch for your feature or bug fix.
  • Ensure your code follows Go conventions and passes all tests.
  • Write tests for new features or bug fixes.
  • Submit a Pull Request with a clear description of your changes.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details

← Back to Networking - HTTP Clients