gurl

gURL: Go URL Request Library

Make a URL request in Go easy.

	var resp struct {
		KeysURL string `json:"keys_url"`
	}

	if err := gurl.Get("https://api.github.com/",
		gurl.WithExpectedCode(200),
		gurl.WithReader(gurl.DecodeAsJSON(&resp)),
	); err != nil {
		log.Fatal(err.Error())
	}

	fmt.Println(resp.KeysURL)
	//Output: https://api.github.com/user/keys

Motivation

Go official net/http package is simple and powerful to control HTTP communication. However we need to write similar code (creating a request, error handling, decoding a response, etc.) in most cases. Major use cases should be able to implement easier like requests in Python.

How-to based Usages

• Passing body data
• Passing query string parameters in URL
• Custom Headers
• JSON Response Content
• Dump response body
• With context.Context
• Error handling
• Testing with your http.Client or http.HandlerFunc

Passing body data

WithBody() and ByReader() simply set io.Reader to read HTTP request body.

	r := bytes.NewReader([]byte("my_test_data"))

	if err := gurl.Post(serverURL,
		gurl.WithBody(gurl.ByReader(r)),
	); err != nil {
		log.Fatal(err.Error())
	}

EncodeAsJSON() supports JSON encoding from struct data to byte data and create a new io.Reader.

	var req struct {
		Name string `json:"name"`
	}

	if err := gurl.Post(serverURL,
		gurl.WithBody(gurl.EncodeAsJSON(req)),
	); err != nil {
		log.Fatal(err.Error())
	}

Also, gurl has EncodeAsURL() to support URL encoding.

	body := map[string]any{
		"color": "blue",
		"text":  "Hello Günter",
	}

	if err := gurl.Post(serverURL,
		// It will send "color=blue&text=Hello+G%C3%BCnter" as request body
		gurl.WithBody(gurl.EncodeAsURL(body)),
	); err != nil {
		log.Fatal(err.Error())
	}

Passing query string parameters in URL

WithParam() option adds query parameter to URL.

	// It will send request to https://www.google.com/search?q=security
	if err := gurl.Get("https://www.google.com/search",
		gurl.WithParam("q", "security"),
	); err != nil {
		log.Fatal(err.Error())
	}

If original URL has query string, WithParam() keeps original query parameters and appends new parameters.

	// It will send request to https://www.google.com/search?q=security&source=hp&sclient=gws-wiz
	if err := gurl.Get("https://www.google.com/search&q=security",
		gurl.WithParam("source", "hp"),
		gurl.WithParam("sclient", "gws-wiz"),
	); err != nil {
		log.Fatal(err.Error())
	}

Custom Headers

WithHeader() can add HTTP header to a request.

	if err := gurl.Get(serverURL,
		gurl.WithHeader("Authorization", "Bearer XXXXXXXX"),
	); err != nil {
		log.Fatal(err.Error())
	}

JSON Response Content

WithReader() and DecodeAsJSON() support to decode JSON formatted response.

	var resp struct {
		KeysURL string `json:"keys_url"`
	}

	if err := gurl.Get("https://api.github.com/",
		gurl.WithReader(gurl.DecodeAsJSON(&resp)),
	); err != nil {
		log.Fatal(err.Error())
	}

	fmt.Println(resp.KeysURL)
	//Output: https://api.github.com/user/keys

Dump response body

CopyStream() calls io.Copy() to read response body and to write given io.Writer. For example, following code saves result of HTTP request to a temp file.

	f, err := os.CreateTemp("", "*.json")
	if err != nil {
		log.Fatal(err.Error())
	}

	if err := gurl.Get("https://api.github.com/",
		gurl.WithReader(gurl.CopyStream(f)),
	); err != nil {
		log.Fatal(err.Error())
	}

With context.Context

WithCtx() will create http.Request with context.Context.

	if err := gurl.Get("https://slow.example.com",
	    gurl.WithCtx(ctx),
	); err != nil {
		log.Fatal(err.Error())
	}

Error handling

gurl uses goerr and keeps response body content to error structure when the request is failed. It can be extracted with errors.As method.

	if err := gurl.Get("https://example.com",
		gurl.WithClient(&errorClient{}),
	); err != nil {
		var goErr *goerr.Error
		if errors.As(err, &goErr) {
			fmt.Println(string(goErr.Values()["body"].([]byte)))
		}
	}
	//Output: crashed!

Testing with your http.Client or http.HandlerFunc

You can use own http.Client that is implemented Do(req *http.Request) (*http.Response, error) method.

type testClient struct{}

func (x *testClient) Do(req *http.Request) (*http.Response, error) {
	fmt.Println(req.URL)
	return &http.Response{
		StatusCode: 200,
		Body:       io.NopCloser(bytes.NewReader([]byte{})),
	}, nil
}

Then, following code will output https://www.google.com/search?q=security.

	client := &testClient{}

	if err := gurl.Get("https://www.google.com/search",
		gurl.WithParam("q", "security"),
		gurl.WithClient(client),
	); err != nil {
		log.Fatal(err.Error())
	}

Also WithHandlerFunc() can be used to test your HTTP server that is implemented ServeHTTP.

type testServer struct{}

func (x testServer) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	fmt.Println(r.URL)
	w.WriteHeader(200)
	w.Write([]byte("hello"))
}

	server := &testServer{}

	if err := gurl.Get("https://www.google.com/search",
		gurl.WithParam("q", "security"),
		gurl.WithHandlerFunc(server.ServeHTTP),
	); err != nil {
		log.Fatal(err.Error())
	}

License

Apache License 2.0