diff --git a/docs/client/client.md b/docs/client/client.md index 70063c6353..70cc51c577 100644 --- a/docs/client/client.md +++ b/docs/client/client.md @@ -8,12 +8,43 @@ sidebar_position: 1 # Client -The Client is used to create a Fiber Client with client-level settings that apply to all requests raise from the client. -Fiber Client also provides an option to override or merge most of the client settings at the request. +The Fiber Client is a powerful HTTP client optimized for high performance and ease of use in server-side applications. Built on top of the robust FastHTTP library, it inherits FastHTTP's high-speed HTTP protocol implementation. The client is designed to make HTTP requests both internally within services or externally to other web services. -It is built top on FastHTTP client. +## Features +- **Lightweight & Fast**: Leveraging the minimalistic design of FastHTTP, the Fiber Client is lightweight and extremely fast. +- **Flexible Configuration**: Configure client-level settings such as timeouts, headers, and more, which apply to all requests. Specific requests can further override or merge these settings. +- **Connection Pooling**: Manages a pool of persistent connections that reduce the overhead of repeatedly establishing connections. +- **Timeouts & Retries**: Supports setting request timeouts and retry mechanisms to handle transient failures. -# TODO: Add more information about gofiber client. +## Usage +To use the Fiber Client, instantiate it with the desired configuration. Here's a simple example: + +```go +package main + +import ( + "fmt" + "time" + + "github.com/gofiber/fiber/v3/client" +) + +func main() { + cc := client.New() + cc.SetTimeout(10 * time.Second) + + // Get request + resp, err := cc.Get("https://httpbin.org/get") + if err != nil { + panic(err) + } + + fmt.Printf("Status: %d\n", resp.StatusCode()) + fmt.Printf("Body: %s\n", string(resp.Body())) +} +``` + +You can check out [examples](examples.md) for more examples! ```go type Client struct { @@ -75,7 +106,7 @@ func New() *Client Config for easy to set the request parameters, it should be noted that when setting the request body will use JSON as the default serialization mechanism, while the priority of Body is higher than FormData, and the priority of FormData is higher than File. -It can be used to configurate request data while sending requests using Get, Post etc. +It can be used to configure request data while sending requests using Get, Post, etc. ```go type Config struct { @@ -164,7 +195,7 @@ func (c *Client) JSONUnmarshal() utils.JSONUnmarshal ## SetJSONUnmarshal -Set json decoder. +Set the JSON decoder. ```go title="Signature" func (c *Client) SetJSONUnmarshal(f utils.JSONUnmarshal) *Client @@ -180,7 +211,7 @@ func (c *Client) XMLMarshal() utils.XMLMarshal ## SetXMLMarshal -SetXMLMarshal Set xml encoder. +SetXMLMarshal sets the XML encoder. ```go title="Signature" func (c *Client) SetXMLMarshal(f utils.XMLMarshal) *Client @@ -196,7 +227,7 @@ func (c *Client) XMLUnmarshal() utils.XMLUnmarshal ## SetXMLUnmarshal -SetXMLUnmarshal Set xml decoder. +SetXMLUnmarshal sets the XML decoder. ```go title="Signature" func (c *Client) SetXMLUnmarshal(f utils.XMLUnmarshal) *Client @@ -205,7 +236,7 @@ func (c *Client) SetXMLUnmarshal(f utils.XMLUnmarshal) *Client ## TLSConfig TLSConfig returns tlsConfig in client. -If client don't have tlsConfig, this function will init it. +If the client doesn't have a tlsConfig, this function will initialize it. ```go title="Signature" func (c *Client) TLSConfig() *tls.Config @@ -565,7 +596,7 @@ func (c *Client) SetCookieJar(cookieJar *CookieJar) *Client ## Get -Get provide an API like axios which send get request. +Get provides an API like axios which sends a get request. ```go title="Signature" func (c *Client) Get(url string, cfg ...Config) (*Response, error) @@ -573,7 +604,7 @@ func (c *Client) Get(url string, cfg ...Config) (*Response, error) ## Post -Post provide an API like axios which send post request. +Post provides an API like axios which send post request. ```go title="Signature" func (c *Client) Post(url string, cfg ...Config) (*Response, error) @@ -581,7 +612,7 @@ func (c *Client) Post(url string, cfg ...Config) (*Response, error) ## Head -Head provide an API like axios which send head request. +Head provides an API like axios which send head request. ```go title="Signature" func (c *Client) Head(url string, cfg ...Config) (*Response, error) @@ -589,7 +620,7 @@ func (c *Client) Head(url string, cfg ...Config) (*Response, error) ## Put -Put provide an API like axios which send put request. +Put provides an API like axios which send put request. ```go title="Signature" func (c *Client) Put(url string, cfg ...Config) (*Response, error) @@ -597,7 +628,7 @@ func (c *Client) Put(url string, cfg ...Config) (*Response, error) ## Delete -Delete provide an API like axios which send delete request. +Delete provides an API like axios which send delete request. ```go title="Signature" func (c *Client) Delete(url string, cfg ...Config) (*Response, error) @@ -605,7 +636,7 @@ func (c *Client) Delete(url string, cfg ...Config) (*Response, error) ## Options -Options provide an API like axios which send options request. +Options provides an API like axios which send options request. ```go title="Signature" func (c *Client) Options(url string, cfg ...Config) (*Response, error) @@ -613,7 +644,7 @@ func (c *Client) Options(url string, cfg ...Config) (*Response, error) ## Patch -Patch provide an API like axios which send patch request. +Patch provides an API like axios which send patch request. ```go title="Signature" func (c *Client) Patch(url string, cfg ...Config) (*Response, error) @@ -621,7 +652,7 @@ func (c *Client) Patch(url string, cfg ...Config) (*Response, error) ## Custom -Custom provide an API like axios which send custom request. +Custom provides an API like axios which send custom request. ```go title="Signature" func (c *Client) Custom(url, method string, cfg ...Config) (*Response, error) @@ -738,4 +769,4 @@ Patch send a patch request use defaultClient, a convenient method. ```go title="Signature" func Patch(url string, cfg ...Config) (*Response, error) -``` \ No newline at end of file +``` diff --git a/docs/client/request.md b/docs/client/request.md index 65251105ce..4b9f54cd79 100644 --- a/docs/client/request.md +++ b/docs/client/request.md @@ -8,7 +8,15 @@ sidebar_position: 2 # Request -Request is the structure contains request data. +The `Request` structure in Gofiber's HTTP client represents an HTTP request. It encapsulates all the necessary information required to send a request to a server. This includes: + +- **URL**: The URL to which the request is sent. +- **Method**: The HTTP method used (GET, POST, PUT, DELETE, etc.). +- **Headers**: HTTP headers that provide additional information about the request or the needed responses. +- **Body**: The data sent with the request, typically used with POST and PUT methods. +- **Query Parameters**: Parameters that are appended to the URL, used to modify the request or to provide additional information. + +This structure is designed to be flexible and efficient, allowing users to easily construct and modify HTTP requests according to their needs. ```go type Request struct { @@ -50,7 +58,7 @@ func AcquireRequest() *Request ## ReleaseRequest ReleaseRequest returns the object acquired via AcquireRequest to the pool. -Do not access the released Request object, otherwise data races may occur. +Do not access the released Request object; otherwise, data races may occur. ```go title="Signature" func ReleaseRequest(req *Request) @@ -216,7 +224,7 @@ func (r *Request) SetParamsWithStruct(v any) *Request ## DelParams -DelParams method deletes single or multiple param fields ant its values. +DelParams method deletes single or multiple param fields and their values. ```go title="Signature" func (r *Request) DelParams(key ...string) *Request @@ -532,7 +540,7 @@ func (r *Request) SetMaxRedirects(count int) *Request ## Get Get sends the GET request. -It sets URL and HTTP method and then it sends the request. +It sets the URL and HTTP method, and then it sends the request. ```go title="Signature" func (r *Request) Get(url string) (*Response, error) @@ -541,7 +549,7 @@ func (r *Request) Get(url string) (*Response, error) ## Post Post sends the POST request. -It sets URL and HTTP method and then it sends the request. +It sets the URL and HTTP method, and then it sends the request. ```go title="Signature" func (r *Request) Post(url string) (*Response, error) @@ -550,7 +558,7 @@ func (r *Request) Post(url string) (*Response, error) ## Head Head sends the HEAD request. -It sets URL and HTTP method and then it sends the request. +It sets the URL and HTTP method, and then it sends the request. ```go title="Signature" func (r *Request) Head(url string) (*Response, error) @@ -559,7 +567,7 @@ func (r *Request) Head(url string) (*Response, error) ## Put Put sends the PUT request. -It sets URL and HTTP method and then it sends the request. +It sets the URL and HTTP method, and then it sends the request. ```go title="Signature" func (r *Request) Put(url string) (*Response, error) @@ -568,7 +576,7 @@ func (r *Request) Put(url string) (*Response, error) ## Delete Delete sends the DELETE request. -It sets URL and HTTP method and then it sends the request. +It sets the URL and HTTP method, and then it sends the request. ```go title="Signature" func (r *Request) Delete(url string) (*Response, error) @@ -577,7 +585,7 @@ func (r *Request) Delete(url string) (*Response, error) ## Options Options sends the OPTIONS request. -It sets URL and HTTP method and then it sends the request. +It sets the URL and HTTP method, and then it sends the request. ```go title="Signature" func (r *Request) Options(url string) (*Response, error) @@ -586,7 +594,7 @@ func (r *Request) Options(url string) (*Response, error) ## Patch Patch sends the PATCH request. -It sets URL and HTTP method and then it sends the request. +It sets the URL and HTTP method, and then it sends the request. ```go title="Signature" func (r *Request) Patch(url string) (*Response, error) @@ -595,7 +603,7 @@ func (r *Request) Patch(url string) (*Response, error) ## Custom Custom sends a request with custom HTTP method. -It sets URL and HTTP method and then it sends the request. +It sets the URL and HTTP method, and then it sends the request. You can use Custom to send requests with methods like TRACE, CONNECT. ```go title="Signature" @@ -969,4 +977,4 @@ Reset clear the File object. ```go title="Signature" func (f *File) Reset() -``` \ No newline at end of file +``` diff --git a/docs/client/response.md b/docs/client/response.md index ed0609bf2b..78a08e3bb6 100644 --- a/docs/client/response.md +++ b/docs/client/response.md @@ -8,7 +8,14 @@ sidebar_position: 3 # Response -Response is the result of a request. This object is used to access the response data. +The `Response` structure in Gofiber's HTTP client represents the server's response to an HTTP request. It contains all the necessary information received from the server. This includes: + +- **Status Code**: The HTTP status code returned by the server (e.g., 200 OK, 404 Not Found). +- **Headers**: HTTP headers received from the server that provide additional information about the response. +- **Body**: The data received from the server, typically in the form of a JSON, XML, or plain text format. +- **Cookies**: Any cookies sent by the server along with the response. + +This structure allows users to easily access and manage the data returned by the server, facilitating efficient handling of HTTP responses. ```go type Response struct { @@ -33,7 +40,7 @@ func AcquireResponse() *Response ## ReleaseResponse ReleaseResponse returns the object acquired via AcquireResponse to the pool. -Do not access the released Response object, otherwise data races may occur. +Do not access the released Response object, otherwise, data races may occur. ```go title="Signature" func ReleaseResponse(resp *Response) @@ -133,4 +140,4 @@ Close method will release Request object and Response object, after call Close p ```go title="Signature" func (r *Response) Close() -``` \ No newline at end of file +``` diff --git a/docs/whats_new.md b/docs/whats_new.md index 735dc345a3..852533e5ef 100644 --- a/docs/whats_new.md +++ b/docs/whats_new.md @@ -227,9 +227,9 @@ DRAFT section ## 🌎 Client package -The Gofiber client has been built from the scratch. It comes with lots of new features like Cookiejar, request/response hooks etc. +The Gofiber client has been completely rebuilt. It includes numerous new features such as Cookiejar, request/response hooks, and more. You can take a look to [client docs](./client/client.md) to see what's new with the client. - + ## 📎 Binding :::caution