https://github.com/lib4u/grequest
Simple golang library for http requests
https://github.com/lib4u/grequest
golang golang-module golang-package http-client http-requests
Last synced: 7 months ago
JSON representation
Simple golang library for http requests
- Host: GitHub
- URL: https://github.com/lib4u/grequest
- Owner: lib4u
- License: mit
- Created: 2025-01-05T09:56:34.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-31T17:20:54.000Z (about 1 year ago)
- Last Synced: 2025-03-30T16:22:59.446Z (12 months ago)
- Topics: golang, golang-module, golang-package, http-client, http-requests
- Language: Go
- Homepage:
- Size: 82 KB
- Stars: 8
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go-cn - Grequest - Simple and lightweight golang package for http requests. based on powerful net/http (网络 / HTTP客户端)
- awesome-go - Grequest - Simple and lightweight golang package for http requests. based on powerful net/http (Networking / HTTP Clients)
- fucking-awesome-go - Grequest - Simple and lightweight golang package for http requests. based on powerful net/http (Networking / HTTP Clients)
- awesome-go-with-stars - Grequest - 01-31 | (Networking / HTTP Clients)
- awesome-go - Grequest - Simple and lightweight golang package for http requests. based on powerful net/http (Networking / HTTP Clients)
README
**A simple and lightweight HTTP client for Go, inspired by Requests (Python) and Guzzle (PHP).**
Grequests provides a declarative, chainable API to streamline HTTP requests in Go, supporting JSON manipulation, form submissions, cookies, file handling, authentication, and proxy configuration—all while remaining lightweight and dependency-free.
---
## **Features**
- **Lightweight & Efficient**: No third-party dependencies, built directly on `net/http`.
- **Flexible Request Handling**: Supports GET, POST, PUT, DELETE, and other HTTP methods.
- **JSON Parsing**: Convert responses into Go structs or string maps.
- **Header & Cookie Management**: Easily set, retrieve, and persist headers and cookies.
- **File Handling**: Upload and download files seamlessly.
- **Authentication**: Supports Basic, Bearer, and custom token authentication.
- **Proxy Support**: Configure custom proxy servers for HTTP requests.
---
## **Installation**
Install Grequests using Go modules:
```sh
go get github.com/lib4u/grequest
```
Or build from source:
```sh
git clone https://github.com/lib4u/grequest.git
cd grequest
go build -o grequest ./
./grequest --version
```
---
## **Usage**
### **Basic GET Request**
```go
req := app.Get("https://jsonplaceholder.typicode.com/todos/1").Do()
fmt.Println(req.Body().GetStrings())
```
### **Parsing JSON Response**
```go
type Todo struct {
UserID int `json:"userId"`
ID int `json:"id"`
Title string `json:"title"`
Completed bool `json:"completed"`
}
var todo Todo
req := app.Get("https://jsonplaceholder.typicode.com/todos/1").Do()
err := req.Body().GetWithJsonStruct(&todo)
if err != nil {
fmt.Println("Error decoding JSON")
}
fmt.Println(todo.Title)
```
### **POST Request with JSON Payload**
```go
data := LoginRequest{
Username: "example",
Password: "12345",
}
req := app.Post("https://example.site/login").Body().SetJson(data).Do()
fmt.Println(req.Status().GetCode())
```
### **Downloading a File**
```go
app.Get("https://example.com/image.png").Do().Body().SaveFile()
```
### **Multipart Form Submission**
```go
req := app.Post("https://example.site/form/")
req.Header().Set("Client", "number_1")
form := req.FormData().WithMultipart()
form.AddField("first_name", "John")
form.AddFile("photo", "my_photo.png")
form.Push()
req.Do()
```
### **Set count of maximum redirects and retry request if get 404 or 500 HTTP code**
```go
req := app.Get("https://jsonplaceholder.typicode.com/todos/1").MaxRedirect(1).RetryIf(404, 500).Do()
fmt.Println(req.Body().GetStrings())
```
### **Set your context**
```go
ctx, cancel := context.WithTimeout(context.Background(), 90*time.Second)
defer cancel()
req := app.Get("https://jsonplaceholder.typicode.com/todos/1").DoWithContext(ctx)
fmt.Println(req.Body().GetStrings())
```
### **Authenticated Requests**
```go
// Basic Authentication
app.Post("https://example.site/secret").Auth().SetBasic("user", "password").Do()
// Bearer Token Authentication
app.Post("https://example.site/secret").Auth().SetBearer("myToken").Do()
// Custom Token Authentication
app.Post("https://example.site/secret").Auth().SetToken("Token", "myToken").Do()
// Custom Header Authentication
app.Post("https://example.site/secret").Auth().SetHeader("JSESSIONID", "12345").Do()
```
### **Cookie Handling**
```go
//Save cookie to file
//By default this saved in cookies/example.site/cookies.json
req := app.Post("https://example.site/cookies")
req.Cookie().Save()
// Load saved cookies form cookies/example.site/cookies.json
reqWithCookie := app.Post("https://example.site/cookies")
reqWithCookie.Cookie().Load()
reqWithCookie.Do()
// Clear cookies
reqWithCookie.Cookie().Clear()
```
---
## **Contributing**
1. Fork the repository and clone it locally.
2. Create a new branch (`git checkout -b feature/branch-name`).
3. Make your changes and commit (`git commit -m "Description of changes"`).
4. Push your changes and create a pull request.
---
## **License**
Grequests is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
For more details, visit the [GitHub repository](https://github.com/lib4u/grequest).
---