gorequest

README

GoRequest -

Simplified HTTP Client inspired by the Node.js request module

Disclaimer

Not all functionality from the original Node.js request module has been yet ported. WIP

Description

GoRequest makes HTTP requests simple and idiomatic. It was implemented and designed to be simple when making HTTP calls.

Installation

$ go get github.com/mscheker/gorequest

Table of Contents

Simple to Use

• With Convenience Methods
• With Request Builder

Request Builder Methods

Authentication

• Basic Authentication
• Bearer Authentication

Convenience Methods

Credits

Simple to Use

With Convenience Methods

package main

import (
    "fmt"

    request "github.com/mscheker/gorequest"
)

func main() {
    resp := request.Get("https://www.google.com")
    
    fmt.Printf("Body: %s \n\r", string(resp.Body()))
    fmt.Printf("Status: %s \n\r", resp.Response().Status)
}

With Request Builder

If you need more control when making requests, the package exposes a constructor for a RequestBuilder object.

package main

import (
    "fmt"

    request "github.com/mscheker/gorequest"
)

func main() {
    resp := request.NewRequestBuilder().WithUrl("https://www.google.com").Build().Do()
    
    fmt.Printf("Body: %s \n\r", string(resp.Body()))
    fmt.Printf("Status: %s \n\r", resp.Response().Status)
}

Request Builder Methods

When building a request, the only required option is the URL; the method will default to GET if none is specified.

• WithUrl - Fully qualified URL.
• WithRFC1738 - Full qualified URL with username and password for Basic Authentication.
• WithMethod - HTTP method (Defaults to "GET").
• WithHeader - HTTP header (Defaults to an empty map).
• WithTextBody - Body for POST and PUT requests. Must be a string. Content-Type header is set to text/plain.
• WithJsonBody - Body for POST and PUT requests. Must be a valid JSON formatted string or a JSON serializable struct. Content-Type header is set to application/json.
• WithBasicAuth - Generates a Base64 encoded string from the username and password specified, and sets the Authorization header to Basic <encoded_string> accordingly.
• WithBearerAuth - Sets the Authorization header to Bearer <your_bearer_token> accordingly.
• WithTimeout - Sets the time limit for requests made by the HTTP client. Defaults to 30 seconds.
• Build - Builds a request object with the specified options. Will panic if a URL has not been set.

Note: Body is ignored for GET, DELETE and HEAD requests.

Authentication

The builder exposes various methods for the different authentication mechanisms that are supported:

• Basic
• Bearer

Basic Authentication

Basic authentication is supported, and it is set when a username and password are provided as part of the WithBasicAuth method.

package main

import (
    "fmt"

    request "github.com/mscheker/gorequest"
)

func main() {
    resp := request.NewRequestBuilder().WithUrl("https://postman-echo.com/basic-auth").WithBasicAuth("postman", "password").Build().Do()

    fmt.Printf("Body: %s \n\r", string(resp.Body()))
    fmt.Printf("Status: %s \n\r", resp.Response().Status)
}

You can also specify basic authentication using the URL itself, as detailed in RFC 1738.

package main

import (
    "fmt"

    request "github.com/mscheker/gorequest"
)

func main() {
    resp := request.NewRequestBuilder().WithRFC1738("https://postman:password@postman-echo.com/basic-auth").Build().Do()

    fmt.Printf("Body: %s \n\r", string(resp.Body()))
    fmt.Printf("Status: %s \n\r", resp.Response().Status)
}

Bearer Authentication

Bearer authentication is supported, and it is set when the bearer value is provided as part of the WithBearerAuth method.

package main

import (
    "fmt"

    request "github.com/mscheker/gorequest"
)

func main() {
    resp := request.NewRequestBuilder().WithUrl("https://your_endpoint").WithBearerAuth("your_bearer_token").Build().Do()

    fmt.Printf("Body: %s \n\r", string(resp.Body()))
    fmt.Printf("Status: %s \n\r", resp.Response().Status)
}

Convenience Methods

There are methods for each different HTTP Verb; the method field is set for you. In the PostText, PostJson, PutText and PutJson methods, the Content-Type header is set accordingly:

• request.Get() - Defaults to method: "GET".
• request.PostText() - Defaults to method: "POST" and Content-Type: "text/plain".
• request.PostJson() - Defaults to method: "POST" and Content-Type: "application/json".
• request.PutText() - Defaults to method: "PUT" and Content-Type: "text/plain".
• request.PutJson() - Defaults to method: "PUT" and Content-Type: "application/json".
• request.Delete() - Defaults to method: "DELETE".
• request.Head() - Defaults to method: "HEAD".

Credits

• Postman Echo for providing a service to test REST clients, API calls, and various auth mechanisms.
• To the team behind the Node.js request module for implementing a robust yet simple to use library which is the inspiration for this package.
• To Demian Lessa for contributing with the revised design and refactoring of the package.

Documentation

Index

• Variables
• func Delete(url string) r.Response
• func Get(url string) r.Response
• func Head(url string) r.Response
• func PostJson(url string, data interface{}) r.Response
• func PostText(url, data string) r.Response
• func PutJson(url string, data interface{}) r.Response
• func PutText(url, data string) r.Response

Variables

var NewRequestBuilder r.RequestBuilderConstructor = r.NewRequestBuilder

*

• Single entry point into the API. A Request instance can only be created
• using a RequestBuilder instance, and this is the only public RequestBuilder
• constructor.

Functions

func Delete

func Delete(url string) r.Response

func Get

func Get(url string) r.Response

func Head

func Head(url string) r.Response

func PostJson

func PostJson(url string, data interface{}) r.Response

func PostText

func PostText(url, data string) r.Response

func PutJson

func PutJson(url string, data interface{}) r.Response

func PutText

func PutText(url, data string) r.Response